GetImage, exemple : décrit l'API WIA (Windows Image Acquisition)
Mise à jour : novembre 2007
L'exemple GetImage décrit les API WIA (Windows Image Acquisition).
L'ensemble API WIA contient des API simples pour les transferts de fichiers, mais il n'existe pas d'appel d'API simple pour les transferts en mémoire. GetImage implémente une fonction wrapper nommée WiaGetImage qui associe la fonctionnalité des API SelectDeviceDlg, DeviceDlg et idtGetBandedData pour encapsuler totalement l'acquisition d'images à l'intérieur d'un unique appel de fonction.
La fonctionnalité principale de l'exemple est le code lui-même. Les fichiers WiaWrap, EventCallback, DataCallback, BitmapUtil et ProgressDlg indiquent la façon correcte pour implémenter les transferts d'images en mémoire. La section « Remarques sur la programmation avec l'API WIA » de ce résumé met en évidence les pièges courants à éviter lors de l'écriture d'une application WIA et l'exemple montre comment les gérer. Vous pouvez lire cet exemple comme une référence ou utiliser directement l'exemple de code en tant que bibliothèque. L'utilisation de chaque fonction est décrite en détail dans les commentaires du fichier d'en-tête.
Note de sécurité : |
---|
Cet exemple de code est fourni pour illustrer un concept et ne doit pas être utilisé dans des applications ou des sites Web, car il peut ne pas illustrer les pratiques de programmation les plus sûres. Microsoft n'assume aucune responsabilité pour tout dommage indirect ou consécutif en cas d'utilisation de l'exemple de code à des fins autres que celles prévues. |
Pour obtenir des exemples et des instructions d'installation :
Dans le menu ? (Aide) de Visual Studio, cliquez sur Exemples.
Pour plus d'informations, consultez Recherche des fichiers d'exemple.
La liste la plus récente et la plus complète d'exemples est disponible en ligne à partir de la page d'exemples Visual Studio 2008.
Des exemples sont également disponibles sur le disque dur de votre ordinateur. Par défaut, des exemples et un fichier Readme sont copiés dans un dossier sous \Program Files\Visual Studio 9.0\Samples\. Pour les éditions Express de Visual Studio, tous les exemples sont accessibles en ligne.
Configuration requise
Cet exemple ne peut être exécuté que sur Windows XP et version ultérieure.
Le Kit de développement logiciel (SDK) Windows Microsoft doit être installé.
Génération et exécution de l'exemple
Pour générer et exécuter cet exemple
Dans Visual Studio, chargez la solution GetImage.sln.
Dans l'Explorateur de solutions, cliquez avec le bouton droit sur le projet, puis cliquez sur Propriétés. Définissez les propriétés suivantes :
Dossier C++, page de propriétés Général : modifiez la propriété Autres répertoires Include pour ajouter le répertoire qui contient les fichiers d'en-tête du Kit de développement logiciel (SDK) Windows (par exemple, c:\Microsoft Kit de développement logiciel (SDK) Windows\include).
Dossier Linker, page de propriétés Général : modifiez la propriété Répertoires de bibliothèques supplémentaires pour ajouter le répertoire qui contient les fichiers bibliothèques du Kit de développement logiciel (SDK) Windows (par exemple, c:\Microsoft Kit de développement logiciel (SDK) Windows\lib).
Dans le menu Générer, cliquez sur Générer.
Dans le menu Déboguer, cliquez sur Exécuter sans débogage.
Le menu Fichier de l'application d'exemple contient une seule commande, appelée À partir d'un scanneur ou d'un appareil-photo numérique. Lorsqu'un périphérique WIA (ou un émulateur de périphérique) est attaché, l'élément de menu est activé. Lorsque l'utilisateur sélectionne la commande de menu, l'exemple affiche séquentiellement les boîtes de dialogue WIA Device Selection, Image Selection et Image Transfer. Les boîtes de dialogue de sélection du périphérique et de l'image sont des boîtes de dialogue courantes fournies par le système et la boîte de dialogue de transfert est implémentée dans cet exemple. Pour finir, l'exemple affiche les images transférées dans les fenêtres enfants.
Fichiers de l'exemple
Fichier |
Description |
---|---|
WiaWrap.cpp |
Contient les fonctions wrapper pour les opérations WIA les plus simples |
WiaWrap.h |
Fichier d'en-tête pour WiaWrap.cpp |
EventCallback.cpp |
Implémente la fonction de rappel pour les événements du périphérique WIA |
EventCallback.h |
Fichier d'en-tête pour EventCallback.cpp |
DataCallback.cpp |
Implémente la fonction de rappel pour les transferts de données |
DataCallback.h |
Fichier d'en-tête pour DataCallback.cpp |
BitmapUtil.cpp |
Contient les fonctions DIB (Device Independent Bitmap, image bitmap indépendante du périphérique) |
BitmapUtil.h |
Fichier d'en-tête pour BitmapUtil.cpp |
ProgressDlg.cpp |
Implémente une boîte de dialogue avancement simple |
ProgressDlg.h |
Fichier d'en-tête pour ProgressDlg.cpp |
GetImage.cpp |
Implémente le point d'entrée principal pour l'application. |
GetImage.rc |
Contient les ressources du projet |
resource.h |
Fichier d'en-tête pour les identificateurs de ressources |
MainWnd.cpp |
Implémente la fenêtre frame principale |
MainWnd.h |
Fichier d'en-tête pour MainWnd.cpp |
BitmapWnd.cpp |
Implémente une fenêtre d'affichage d'image |
BitmapWnd.h |
Fichier d'en-tête pour BitmapWnd.cpp |
StdAfx.cpp |
Fichiers d'en-tête précompilés |
StdAfx.h |
Inclut les fichiers système standard fréquemment utilisés |
Remarques sur la programmation avec l'API WIA
Il est recommandé que les applications permettent la sélection du périphérique et de l'image via un élément de menu appelé "À partir d'un scanneur ou d'un appareil-photo numérique" dans le menu Fichier. Cet élément est grisé si aucun périphérique WIA n'est disponible sur le système.
Il est recommandé que les développeurs d'applications testent leurs applications avec des appareils photo série et USB et des scanneurs à plat, à défilement et avec chargeur automatique de documents. Les émulateurs de périphériques logiciels disponibles sur Windows DDK peuvent également être utilisés pour le test.
En règle générale, les scanneurs à défilement ne connaissent pas la hauteur de l'image lorsque le transfert de l'image commence, c'est pourquoi ils retournent 0 pour la taille de l'image et pour la hauteur de l'image dans l'en-tête de la bitmap. Dans ce cas, la fonction de rappel doit être en mesure d'étendre sa mémoire tampon lorsque de nouvelles données arrivent et doit calculer explicitement la hauteur à la fin du transfert.
Lors de l'utilisation de l'API DeviceDlg sur un bac d'alimentation automatique de documents (ADF, Automatic Document Feeder), l'API définit l'ADF afin qu'il numérise une page. Si vous souhaitez plusieurs pages, l'application doit explicitement définir pour WIA_DPS_PAGES le nombre de pages demandées ou la valeur ALL_PAGES.
Les API SelectDeviceDlg, DeviceDlg, idtGetData et idtGetBandedData retournent S_FALSE si l'utilisateur annule, c'est pourquoi il n'est pas suffisant de vérifier la valeur de retour avec la macro SUCCEEDED. Le programmeur doit explicitement sélectionner S_FALSE. De même, les API ReadMultiple et WriteMultiple retournent S_FALSE lorsque les arguments de la fonction sont corrects, mais la fonction ne peut pas exécuter l'opération demandée, c'est pourquoi le programmeur doit explicitement vérifier la valeur de retour par rapport à S_FALSE.
Si l'application souhaite afficher une boîte de dialogue avancement qui peut être annulée, elle doit afficher cette boîte de dialogue dans un thread séparé. Le thread de transfert de données sera bloqué jusqu'à la fin du transfert, il ne sera donc pas en mesure de traiter les messages dès leur arrivée. Si la boîte de dialogue avancement est créée dans le même thread, la boîte de dialogue (et le bouton Annuler) seront lents pour l'entrée d'utilisateur.
Le transfert de données peut être annulé uniquement lorsque BandedDataCallback est retourné. Dans la mesure où BandedDataCallback peut être appelé très rapidement, l'application doit indiquer à l'utilisateur que l'opération d'annulation est en cours. Par exemple, elle peut désactiver le bouton Annuler ou afficher un message d'attente.
Mots clés
Cet exemple illustre l'utilisation des mots clés suivants :
IWiaDevMgr, IWiaDevMgr::SelectDeviceDlg, IWiaEventCallback, IWiaEventCallback::ImageEventCallback, IWiaItem, IWiaItem::DeviceDlg, IWiaPropertyStorage, IWiaPropertyStorage::ReadMultiple, IWiaPropertyStorage::WriteMultiple, IWiaDataTransfer, IWiaDataTransfer::idtGetBandedData, IWiaDataCallback, IWiaDataCallback::BandedDataCallback