GetImage-Beispiel: Demonstriert die Windows Image Acquisition-API
Aktualisiert: November 2007
Das GetImage-Beispiel veranschaulicht die Schnittstellen für Anwendungsprogrammierung (APIs) von WIA (Windows Image Acquisition).
Der WIA-API-Satz enthält einfache APIs für die Dateiübertragung, jedoch keinen einfachen API-Aufruf für die Übertragung im Speicher. GetImage implementiert eine Wrapperfunktion mit dem Namen WiaGetImage, die die Funktionen der APIs von SelectDeviceDlg, DeviceDlg und idtGetBandedData für das vollständige Einschließen des Bildabrufs innerhalb eines einzelnen Funktionsaufrufs vereint.
Das Hauptfeature des Beispiels ist der Code selbst. Die Dateien WiaWrap, EventCallback, DataCallback, BitmapUtil und ProgressDlg zeigen die korrekte Methode für die Implementierung der speicherinternen Bildübertragung. Die "Hinweise zum Programmieren mit der WIA-API" weiter unten in dieser Zusammenfassung erläutern die möglichen Fehlerquellen beim Schreiben einer WIA-Anwendung und verdeutlichen deren Handhabung anhand eines Beispiels. Sie können dieses Beispiel als Referenz oder den Beispielcode direkt als Bibliothek verwenden. Die Verwendung der einzelnen Funktionen wird in den Anmerkungen zur Headerdatei erläutert.
.gif "Sicherheitshinweis") Sicherheitshinweis: |
|---|
Dieser Beispielcode dient dazu, ein Konzept zu veranschaulichen. Er sollte nicht für Anwendungen oder Websites verwendet werden, da dieser Code unter Umständen nicht die sicherste Codierungstechnik darstellt. Microsoft übernimmt keine Haftung für beiläufig entstandene Schäden oder Folgeschäden, falls der Beispielcode nicht bestimmungsgemäß verwendet wird. |
So rufen Sie Beispiele und Anweisungen für ihre Installation ab
Klicken Sie in Visual Studio im Menü Hilfe auf Beispiele.
Weitere Informationen finden Sie unter Suchen von Beispieldateien.
Die neueste Version und vollständige Liste mit Beispielen ist online unter Visual Studio 2008 Samples verfügbar.
Sie können auch Beispiele auf der Festplatte des Computers suchen. Standardmäßig werden Beispiele und eine Infodatei in einen Ordner unter \Programme\Visual Studio 9.0\Samples\ kopiert. Für Express Editions von Visual Studio sind alle Beispiele online verfügbar.
Anforderungen
Dieses Beispiel kann lediglich unter Windows XP und höher ausgeführt werden.
Microsoft Windows SDK muss installiert sein.
Erstellen und Ausführen des Beispiels
So erstellen Sie dieses Beispiel und führen es aus
Laden Sie in Visual Studio die Projektmappe GetImage.sln.
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt, und klicken Sie auf Eigenschaften. Legen Sie die folgenden Eigenschaften fest:
C++-Ordner, Eigenschaftenseite Allgemein: Ändern Sie zum Hinzufügen des Verzeichnisses, das die Windows SDK-Headerdateien enthält (beispielsweise C:\Microsoft Windows SDK\include) die Eigenschaft Zusätzliche Includeverzeichnisse.
Linker-Ordner, Eigenschaftenseite Allgemein: Ändern Sie zum Hinzufügen des Verzeichnisses, das die Windows SDK-Bibliotheksdateien enthält (beispielsweise C:\Microsoft Windows SDK\lib) die Eigenschaft Zusätzliche Bibliotheksverzeichnisse.
Klicken Sie im Menü Erstellen auf die Option Erstellen.
Klicken Sie im Menü Debuggen auf Starten ohne Debuggen.
Die Beispielanwendung besitzt in ihrem Menü Datei nur den Befehl Von Scanner oder Kamera. Wenn ein WIA-Gerät (oder ein Geräteemulator) angeschlossen ist, wird das Menüelement aktiviert. Wenn der Benutzer den Menübefehl auswählt, zeigt das Beispiel der Reihe nach die Dialogfelder WIA-Geräteauswahl, Bildauswahl und Bildübertragung an. Bei den Dialogfeldern für die Geräte- und Bildauswahl handelt es sich um die allgemeinen Systemdialogfelder. Das Dialogfeld für die Bildübertragung wird in diesem Beispiel implementiert. Schließlich zeigt das Beispiel die übertragenen Bilder in untergeordneten Fenstern an.
Dateien im Beispiel
Datei |
Beschreibung |
|---|---|
WiaWrap.cpp |
Enthält Wrapperfunktionen für einfachere WIA-Operationen |
WiaWrap.h |
Headerdatei für WiaWrap.cpp |
EventCallback.cpp |
Implementiert die Rückruffunktion für WIA-Geräteereignisse |
EventCallback.h |
Headerdatei für EventCallback.cpp |
DataCallback.cpp |
Implementiert die Rückruffunktion für Datenübertragungen |
DataCallback.h |
Headerdatei für DataCallback.cpp |
BitmapUtil.cpp |
Enthält Funktionen für geräteunabhängige Bitmaps (DIB – Device Independent Bitmap) |
BitmapUtil.h |
Headerdatei für BitmapUtil.cpp |
ProgressDlg.cpp |
Implementiert ein einfaches Fortschrittsdialogfeld |
ProgressDlg.h |
Headerdatei für ProgressDlg.cpp |
GetImage.cpp |
Implementiert den Haupteinstiegspunkt für die Anwendung |
GetImage.rc |
Enthält die Projektressourcen |
resource.h |
Headerdatei für die Ressourcenbezeichner |
MainWnd.cpp |
Implementiert das Hauptrahmenfenster |
MainWnd.h |
Headerdatei für MainWnd.cpp |
BitmapWnd.cpp |
Implementiert ein Bildanzeigefenster |
BitmapWnd.h |
Headerdatei für BitmapWnd.cpp |
StdAfx.cpp |
Vorkompilierte Headerdatei |
StdAfx.h |
Enthält häufig verwendete Standardsystemdateien |
Hinweise zum Programmieren mit der WIA-API
Es empfiehlt sich, dass die Geräte- und Bildauswahl in einer Anwendung über das Menüelement Von Scanner oder Kamera des Menüs Datei möglich ist. Dieses Menüelement könnte grau unterlegt werden, wenn keine WIA-Geräte im System vorhanden sind.
Bei der Entwicklung von Anwendungen sollten diese sowohl mit seriellen als auch mit USB-Kameras, Flachbett-, Hand- und ADF-Scannern getestet werden. Zudem können zum Testen die auf dem Windows DDK verfügbaren softwarebasierten Geräteemulatoren verwendet werden.
Handscanner kennen im Allgemeinen zu Beginn der Datenübertragung die Bildhöhe nicht, sodass sie für die Bildgröße und die Bildhöhe im Bitmapheader unter Umständen 0 zurückgeben. In diesem Fall sollte die Rückruffunktion in der Lage sein, den Puffer beim Eingehen neuer Daten zu erweitern und die Bildhöhe nach Abschluss der Übertragung genau zu berechnen.
Wenn am automatischen Papiereinzug (ADF) DeviceDlg API verwendet wird, legt die API für den Papiereinzug fest, dass nur eine Seite gescannt wird. Wenn mehrere Seiten gescannt werden sollen, sollte die Anwendung für WIA_DPS_PAGES ausdrücklich die Anzahl der gewünschten Seiten oder den Wert ALL_PAGES festlegen.
Die APIs SelectDeviceDlg, DeviceDlg, idtGetData und idtGetBandedData geben den Wert S_FALSE zurück, wenn der Benutzer den Vorgang abbricht, daher ist es nicht ausreichend, den Rückgabewert mit dem SUCCEEDED-Makro zu überprüfen. Der Programmierer muss ausdrücklich S_FALSE überprüfen. Gleichzeitig geben die APIs ReadMultiple und WriteMultiple S_FALSE zurück, wenn die Funktionsargumente zwar korrekt sind, die Funktion die angeforderte Operation jedoch nicht ausführen kann, daher muss der Rückgabewert beim Programmieren ausdrücklich anhand von S_FALSE überprüft werden.
Wenn die Anwendung ein Fortschrittsdialogfeld anzeigen soll, in dem der Vorgang abgebrochen werden kann, sollte dieses Dialogfeld in einem separaten Thread angezeigt werden. Der Datenübertragungsthread wird unterbrochen, bis die Übertragung abgeschlossen ist, daher können die Fenstermeldungen nicht im Moment ihrer Ankunft verarbeitet werden. Wenn das Fortschrittsdialogfeld im selben Thread erstellt wird, reagiert das Dialogfeld (und die Abbruchschaltfläche) sehr träge auf die Benutzereingabe.
Die Datenübertragung kann nur abgebrochen werden, wenn BandedDataCallback zurückgegeben wird. Da BandedDataCallback alle paar Sekunden aufgerufen werden kann, sollte die Anwendung dem Benutzer mitteilen, dass die Abbruchoperation durchgeführt wird. Es könnte beispielsweise die Abbruchschaltfläche deaktiviert oder eine Wartemeldung angezeigt werden.
Schlüsselwörter
Dieses Beispiel demonstriert die Verwendung der folgenden Schlüsselwörter:
IWiaDevMgr, IWiaDevMgr::SelectDeviceDlg, IWiaEventCallback, IWiaEventCallback::ImageEventCallback, IWiaItem, IWiaItem::DeviceDlg, IWiaPropertyStorage, IWiaPropertyStorage::ReadMultiple, IWiaPropertyStorage::WriteMultiple, IWiaDataTransfer, IWiaDataTransfer::idtGetBandedData, IWiaDataCallback, IWiaDataCallback::BandedDataCallback