Architettura di gestione degli errori WIA

L'architettura di gestione degli errori WIA è costituita da tre parti. Sistema operativo, driver e applicazione. Il meccanismo di gestione degli errori si basa sui trasferimenti di dati basati su flusso. Questo modello di trasferimento è disponibile in Windows Vista e nei sistemi operativi successivi. I driver WIA devono essere scritti per usare questo modello di trasferimento se sono in grado di supportare questa nuova metodologia di gestione degli errori. Analogamente, le applicazioni devono essere scritte anche per supportare il modello di trasferimento basato su flusso per poter partecipare a questa nuova architettura di gestione degli errori.

La gestione degli errori WIA è costituita da componenti forniti dal sistema, forniti da IHV e ISV. Il diagramma seguente illustra il fornitore di ogni componente.

Sono disponibili tre gestori di errori possibili: il gestore degli errori dell'applicazione, il gestore degli errori del driver e il gestore degli errori predefinito. Questi tre gestori di errori sono illustrati nel diagramma seguente.

L'immagine mostra anche la gerarchia in cui vengono tentati questi tre gestori di errori dal callback del proxy WIA.

Nella maggior parte degli aspetti, questi gestori sono identici. Esistono tuttavia alcune differenze. Il gestore degli errori dell'applicazione implementa l'interfaccia IWiaAppErrorHandler , mentre l'estensione dell'errore del driver e il gestore errori predefinito implementano l'interfaccia IWiaErrorHandler . Il gestore degli errori dell'applicazione userà anche IWiaTransferCallback, che deve essere implementato nell'oggetto callback.

Il codice di stato del dispositivo viene passato a un gestore di errori con il parametro hrStatus di IWiaErrorHandler::ReportStatus. Si tratta dello stesso valore impostato dal minidriver nel parametro hrErrorStatus del metodo IWiaTransferCallback::WiaTransferParams .

Se il parametro hrStatus è impostato su SEVERITY_SUCCESS, rappresenta un ritardo non irreversibile. Ciò significa che l'interfaccia utente di gestione degli errori deve semplicemente fornire una finestra di dialogo senza modalità, informazioni e una possibilità di annullare il trasferimento. L'interfaccia utente deve essere ignorata la volta successiva che il gestore degli errori riceve un messaggio con un valore hrStatus diverso(se il gestore errori supporta questo messaggio).

Nota È possibile visualizzare contemporaneamente una sola finestra di dialogo del gestore degli errori senza modalità.

Un gestore di errori deve visualizzare l'interfaccia utente modale in risposta a un messaggio di stato del dispositivo di SEVERITY_ERROR.

Sono presenti quattro componenti coinvolti nella gestione degli errori WIA:

Minidriver WIA
Il minidriver può ora usare, nuovo per Windows Vista, WIA_TRANSFER_MSG_DEVICE_STATUS messaggio di stato del dispositivo per indicare che qualcosa è successo a livello di dispositivo. Quando il driver invia questo messaggio, deve anche impostare il parametro hrErrorStatus (e possibilmente anche lPercentComplete) del metodo IWiaTransferCallback::WiaTransferParams . Il codice di stato può essere un errore o un'informazione. In caso di codice di stato dell'errore, è necessario un intervento dell'utente per il ripristino dall'errore, fornendo che l'errore sia recuperabile. Un driver può impostare hrErrorStatus su un valore WIA HRESULT predefinito, ad esempio WIA_STATUS_WARMING_UP o creare un valore HRESULT personalizzato.

Gestore degli errori dell'applicazione
Per consentire a un'applicazione di abilitare la gestione degli errori, deve implementare l'interfaccia IWiaAppErrorHandler . Questa interfaccia viene implementata dall'oggetto callback dell'applicazione passato ai metodi IWiaTransfer::D ownload e IWiaTransfer::Upload . Questo oggetto callback è necessario per implementare l'interfaccia IWiaTransferCallback . Implementando IWiaAppErrorHandler, un'applicazione indica che consente ai gestori degli errori di essere richiamati durante i trasferimenti di dati.

Gestore degli errori del driver
Il gestore degli errori del driver è un'estensione del driver che deve implementare l'interfaccia IWiaErrorHandler. Il gestore degli errori può gestire e visualizzare l'interfaccia utente per qualsiasi codice di stato; questi codici di stato includono codici di stato definiti da WIA e codici di stato specifici del driver.

Gestore degli errori predefinito
Il gestore degli errori predefinito viene implementato da WIA. Gestisce e visualizza l'interfaccia utente per un numero di messaggi di stato del dispositivo generici. Questi messaggi possono essere sia informativi che errori, ad esempio: WIA_ERROR_PAPER_JAM e WIA_STATUS_WARMING_UP.

Il proxy WIA non gestisce i messaggi di errore stessi. Il proxy WIA offre invece ai gestori degli errori la possibilità di gestire un messaggio di stato del dispositivo.

Il gestore degli errori fornisce l'interfaccia utente che consente all'utente di provare a inserire il sistema in uno stato in cui il trasferimento dei dati può essere continuato o annullato.

Quando si riceve un messaggio di WIA_TRANSFER_MSG_DEVICE_STATUS, il proxy WIA chiama prima il metodo IWiaAppErrorHandler dell'applicazione::ReportStatus . Se la routine di callback dell'applicazione non gestisce il codice di stato del dispositivo, il proxy WIA richiama l'implementazione IWiaErrorHandler::ReportStatus e infine il proxy WIA richiama l'implementazione IWiaErrorHandler::ReportStatus del gestore degli errori predefinito. Se un determinato gestore non esiste (ad esempio, il driver potrebbe non venire con un'estensione di gestione degli errori) o se il gestore dello stato del dispositivo del driver restituisce WIA_STATUS_NOT_HANDLED, indicando che il gestore del driver non supporta il codice del dispositivo, il gestore successivo della catena avrà una possibilità. Una volta gestito un messaggio di stato del dispositivo, il callback proxy WIA restituirà correttamente o senza esito negativo. Quindi, se il metodo ReportStatus del gestore degli errori del driver restituisce S_OK per ogni messaggio, il gestore degli errori predefinito non otterrà mai la possibilità di gestire uno dei messaggi di stato del dispositivo.

Se nessun gestore di errori supporta un messaggio di stato del dispositivo con SEVERITY_ERROR (messaggio di errore), il proxy WIA restituirà nuovamente l'errore di stato al driver, che a sua volta dovrebbe arrestare il trasferimento. Il driver deve restituire questo valore HRESULT da IWiaMiniDrv::d rvAcquireItemData e l'applicazione riceverà questo valore HRESULT da IWiaTransfer::D ownload o IWiaTransfer::Upload.

Se nessun gestore di errori gestisce un messaggio di stato del dispositivo con SEVERITY_SUCCESS (messaggio informativo), il proxy WIA restituirà S_OK al driver.

Nota La routine di callback dell'applicazione , IWiaTransferCallback::TransferCallback, non riceverà mai un messaggio con lMessage impostato su WIA_TRANSFER_MSG_DEVICE_STATUS. Questi messaggi verranno invece inviati ai gestori degli errori.

Le interfacce IWiaTransferCallback, IWiaAppErrorHandler e IWiaTransfer sono descritte nella documentazione di Microsoft Windows SDK.