GetImage Sample: Demonstrates the Windows Image Acquisition API
The GetImage sample demonstrates the Windows Image Acquisition (WIA) application programming interfaces (APIs).
The WIA API set contains simple APIs for file transfers, but there is no simple API call for in-memory transfers. GetImage implements a wrapper function named WiaGetImage that combines the functionality of the SelectDeviceDlg, DeviceDlg, and idtGetBandedData APIs to completely encapsulate image acquisition within a single function call.
The main feature of the sample is the code itself. The files WiaWrap, EventCallback, DataCallback, BitmapUtil, and ProgressDlg show the correct way to implement the in-memory image transfers. The "Notes on Programming with the WIA API" section later in this abstract highlights the common pitfalls while writing a WIA application, and the sample shows how to handle these. You can read this sample as a reference or directly use the sample code as a library. Usage of each function is described in detail in the header file comments.
.gif "Security note") Security Note: |
|---|
This sample code is provided to illustrate a concept and should not be used in applications or Web sites, as it may not illustrate the safest coding practices. Microsoft assumes no liability for incidental or consequential damages should the sample code be used for purposes other than as intended. |
To get samples and instructions for installing them:
On the Visual Studio Help menu, click Samples.
For more information, see Visual Studio Samples.
The most recent version and complete list of samples is available online from the Visual Studio 2008 Samples page.
You can also locate samples on your computer's hard disk. By default, samples and a Readme file are copied into a folder under \Program Files\Visual Studio 9.0\Samples\. For Express editions of Visual Studio, all samples are located online.
Requirements
This sample can only be run on Windows XP and later.
The Microsoft Windows SDK must be installed.
Building and Running the Sample
To build and run this sample
In Visual Studio, load the solution GetImage.sln.
In Solution Explorer, right-click the project and click Properties. Set the following properties:
C++ folder, General property page: modify the Additional Include Directories property to add the directory which contains the Windows SDK header files (for example, c:\Microsoft Windows SDK\include).
Linker folder, General property page: modify the Additional LibraryDirectories property to add the directory which contains the Windows SDK library files (for example, c:\Microsoft Windows SDK\lib).
From the Build menu, click Build.
From the Debug menu, click Start Without Debugging.
The sample application has a single command on its File menu, named From scanner or camera. When a WIA device (or a device emulator) is attached, the menu item becomes enabled. When the user selects the menu command, the sample will sequentially display the WIA Device Selection dialog box, Image Selection dialog box, and Image Transfer dialog box. The device and image selection dialog boxes are the common dialog boxes supplied by the system, and the transfer dialog box is implemented in this sample. Finally, the sample will display the transferred image(s) in child window(s).
Files in the Sample
File |
Description |
|---|---|
WiaWrap.cpp |
Contains wrapper functions for simpler WIA operations |
WiaWrap.h |
Header file for WiaWrap.cpp |
EventCallback.cpp |
Implements the callback function for WIA device events |
EventCallback.h |
Header file for EventCallback.cpp |
DataCallback.cpp |
Implements the callback function for data transfers |
DataCallback.h |
Header file for DataCallback.cpp |
BitmapUtil.cpp |
Contains device independent bitmap (DIB) functions |
BitmapUtil.h |
Header file for BitmapUtil.cpp |
ProgressDlg.cpp |
Implements a simple progress dialog |
ProgressDlg.h |
Header file for ProgressDlg.cpp |
GetImage.cpp |
Implements the main entry point for the application |
GetImage.rc |
Contains the project resources |
resource.h |
Header file for the resource identifiers |
MainWnd.cpp |
Implements the main frame window |
MainWnd.h |
Header file for MainWnd.cpp |
BitmapWnd.cpp |
Implements an image display window |
BitmapWnd.h |
Header file for BitmapWnd.cpp |
StdAfx.cpp |
Precompiled headers file |
StdAfx.h |
Includes frequently used standard system files |
Notes on Programming with the WIA API
It is recommended that applications make device and image selection available through a menu item named From Scanner or Camera... on the File menu. This item could be grayed if there are no WIA devices on the system.
It is recommended that application developers test their applications with serial and USB cameras, and flatbed, scroll-fed, and ADF scanners. Also, software-only device emulators available on the Windows DDK can be used for testing.
Scroll-fed scanners generally do not know the image height when the data transfer starts, so they may return 0 for the image size and for the image height in the bitmap header. In this case, the callback function should be able to expand its buffer when new data arrives and should explicitly calculate the height when the transfer completes.
When using the DeviceDlg API on an automatic document feeder (ADF), the API will set the ADF to scan one page. If multiple pages are desired, the application should explicitly set WIA_DPS_PAGES to the number of pages it requests or to the ALL_PAGES value.
The SelectDeviceDlg, DeviceDlg, idtGetData, and idtGetBandedData APIs return S_FALSE if the user cancels, so it is not sufficient to check the return value with the SUCCEEDED macro. The programmer must explicitly check S_FALSE. Similarly, the ReadMultiple and WriteMultiple APIs return S_FALSE when the function arguments are correct, but the function cannot perform the requested operation, so the programmer must explicitly check the return value against S_FALSE.
If the application wants to display a progress dialog box that can be canceled, it should display the dialog box in a separate thread. The data transfer thread will be blocked until the transfer is complete, so it will not be able to process the window messages as soon as they arrive. If the progress dialog box is created in the same thread, the dialog box (and the cancel button) will be very sluggish to user input.
The data transfer can be canceled only when BandedDataCallback returns. Since BandedDataCallback may be called every few seconds, the application should indicate to the user that the cancel operation is in progress. For example, it can disable the cancel button, or display a wait message.
Keywords
This sample demonstrates the following keywords:
IWiaDevMgr, IWiaDevMgr::SelectDeviceDlg, IWiaEventCallback, IWiaEventCallback::ImageEventCallback, IWiaItem, IWiaItem::DeviceDlg, IWiaPropertyStorage, IWiaPropertyStorage::ReadMultiple, IWiaPropertyStorage::WriteMultiple, IWiaDataTransfer, IWiaDataTransfer::idtGetBandedData, IWiaDataCallback, IWiaDataCallback::BandedDataCallback