Architecture de gestion des erreurs WIA

L’architecture de gestion des erreurs WIA se compose de trois parties. Le système d’exploitation, le pilote et l’application. Le mécanisme de gestion des erreurs s’appuie sur les transferts de données basés sur le flux. Ce modèle de transfert est disponible dans Windows Vista et les systèmes d’exploitation ultérieurs. Les pilotes WIA doivent être écrits pour utiliser ce modèle de transfert s’ils doivent prendre en charge cette nouvelle méthodologie de gestion des erreurs. De même, les applications doivent également être écrites pour prendre en charge le modèle de transfert basé sur le flux pour pouvoir participer à cette nouvelle architecture de gestion des erreurs.

La gestion des erreurs WIA comprend des composants fournis par le système, fournis par IHV et fournis par un éditeur de logiciels indépendants. Le diagramme suivant illustre le fournisseur de chaque composant.

Il existe trois gestionnaires d’erreurs possibles : le gestionnaire d’erreurs d’application, le gestionnaire d’erreurs du pilote et le gestionnaire d’erreurs par défaut. Ces trois gestionnaires d’erreurs sont illustrés dans le diagramme suivant.

L’image montre également la hiérarchie dans laquelle ces trois gestionnaires d’erreurs sont essayés par le rappel du proxy WIA.

Dans la plupart des aspects, ces gestionnaires sont identiques. Il existe cependant quelques différences. Le gestionnaire d’erreurs d’application implémente l’interface IWiaAppErrorHandler , tandis que l’extension de remise des erreurs du pilote et le gestionnaire d’erreurs par défaut implémentent l’interface IWiaErrorHandler . Le gestionnaire d’erreurs d’application utilise également IWiaTransferCallback, qui doit être implémenté dans l’objet de rappel.

Le code status de l’appareil est passé dans un gestionnaire d’erreurs avec le paramètre hrStatus de IWiaErrorHandler::ReportStatus. Il s’agit de la même valeur que celle définie par le minidriver dans le paramètre hrErrorStatus de la méthode IWiaTransferCallback::WiaTransferParams .

Si le paramètre hrStatus est défini sur SEVERITY_SUCCESS, il représente un délai non fatal. Cela signifie que l’interface utilisateur de gestion des erreurs doit simplement fournir une boîte de dialogue d’information sans mode et une possibilité d’annuler le transfert. L’interface utilisateur doit être ignorée la prochaine fois que le gestionnaire d’erreurs reçoit un message avec une valeur hrStatus différente (si le gestionnaire d’erreurs prend en charge ce message).

Note Une seule boîte de dialogue de gestionnaire d’erreurs sans mode peut être affichée en même temps.

Un gestionnaire d’erreurs doit afficher l’interface utilisateur modale en réponse à un message d’appareil status de SEVERITY_ERROR.

Quatre composants sont impliqués dans la gestion des erreurs WIA :

Le minidriver WIA
Le minidriver peut maintenant utiliser le, nouveau pour Windows Vista, WIA_TRANSFER_MSG_DEVICE_STATUS appareil status message pour indiquer qu’un problème s’est produit au niveau de l’appareil. Lorsque le pilote envoie ce message, il doit également définir le paramètre hrErrorStatus (et éventuellement aussi lPercentComplete) de la méthode IWiaTransferCallback::WiaTransferParams . Le code status peut être une erreur ou des informations. En cas d’erreur status code, l’intervention de l’utilisateur est nécessaire pour récupérer l’erreur, à condition que l’erreur soit récupérable. Un pilote peut définir hrErrorStatus sur une valeur WIA HRESULT prédéfinie, telle que WIA_STATUS_WARMING_UP, ou créer son propre HRESULT personnalisé.

Gestionnaire d’erreurs d’application
Pour qu’une application puisse activer la gestion des erreurs, elle doit implémenter l’interface IWiaAppErrorHandler . Cette interface est implémentée par l’objet de rappel de l’application qu’elle a transmis aux méthodes IWiaTransfer::D ownload et IWiaTransfer::Upload . Cet objet de rappel est nécessaire pour implémenter l’interface IWiaTransferCallback . En implémentant IWiaAppErrorHandler, une application indique qu’elle permet d’appeler des gestionnaires d’erreurs pendant les transferts de données.

Gestionnaire d’erreurs du pilote
Le gestionnaire d’erreurs du pilote est une extension de pilote qui doit implémenter l’interface IWiaErrorHandler. Le gestionnaire d’erreurs peut gérer et afficher l’interface utilisateur pour n’importe quel code status ; ces codes status incluent des codes status définis par WIA ainsi que des codes status spécifiques au pilote.

Gestionnaire d’erreurs par défaut
Le gestionnaire d’erreurs par défaut est implémenté par WIA. Il gère et affiche l’interface utilisateur pour un certain nombre de messages génériques status d’appareil. Ces messages peuvent être à la fois d’information et d’erreur, par exemple : WIA_ERROR_PAPER_JAM et WIA_STATUS_WARMING_UP.

Le proxy WIA ne gère pas les messages d’erreur lui-même. Au lieu de cela, le proxy WIA donne aux gestionnaires d’erreurs la possibilité de gérer un appareil status message.

Le gestionnaire d’erreurs fournit l’interface utilisateur qui permet à l’utilisateur d’essayer de placer le système dans un état où le transfert de données peut être poursuivi ou annulé.

Lors de la réception d’un message WIA_TRANSFER_MSG_DEVICE_STATUS, le proxy WIA appelle d’abord la méthode IWiaAppErrorHandler::ReportStatus du gestionnaire d’erreurs d’application. Si la routine de rappel d’application ne gère pas l’appareil status code, le proxy WIA appelle l’implémentation IWiaErrorHandler::ReportStatus du gestionnaire d’erreurs du pilote, et enfin le proxy WIA appelle l’implémentation IWiaErrorHandler::ReportStatus du gestionnaire d’erreurs par défaut. Si un gestionnaire donné n’existe pas (par exemple, le pilote n’est peut-être pas fourni avec une extension de gestion des erreurs), ou si le gestionnaire de status de périphérique du pilote retourne WIA_STATUS_NOT_HANDLED, indiquant que le gestionnaire du pilote ne prend pas en charge le code de l’appareil, le gestionnaire suivant de la chaîne aura la possibilité. Une fois qu’un appareil status message est géré, avec succès ou échec, le rappel du proxy WIA est retourné. Par conséquent, si la méthode ReportStatus du gestionnaire d’erreurs du pilote retourne S_OK pour chaque message, le gestionnaire d’erreurs par défaut n’aura jamais la possibilité de gérer les messages status de l’appareil.

Si aucun gestionnaire d’erreurs ne prend en charge un message de status d’appareil avec SEVERITY_ERROR (message d’erreur), le proxy WIA retourne l’erreur status au pilote, qui à son tour doit arrêter le transfert. Le pilote doit retourner cette valeur HRESULT à partir de IWiaMiniDrv::d rvAcquireItemData et l’application recevra ce HRESULT de IWiaTransfer::D ownload ou IWiaTransfer::Upload.

Si aucun gestionnaire d’erreurs ne gère un message d’appareil status avec SEVERITY_SUCCESS (message d’information), le proxy WIA retourne S_OK au pilote.

Note La routine de rappel de l’application, IWiaTransferCallback::TransferCallback, ne recevra jamais de message avec lMessage défini sur WIA_TRANSFER_MSG_DEVICE_STATUS. Au lieu de cela, ces messages seront envoyés aux gestionnaires d’erreurs.

Les interfaces IWiaTransferCallback, IWiaAppErrorHandler et IWiaTransfer sont décrites dans la documentation Microsoft Windows SDK.