GetImage
Summary
-------
GetImage is a sample application for the demonstration of the Windows Image
Acquisition (WIA) application programming interfaces (API).
The WIA API set contains simple API's for file transfers, but there is no
simple API call for in-memory tranfers.
GetImage implements a wrapper function named WiaGetImage that combines the
functionality of SelectDeviceDlg, DeviceDlg and idtGetBandedData API's to
completely encapsulate image acquisition within a single function call.
To compile and run GetImage, open the project file GetImage.dsp
Files
-----
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.dsp: VC 6.0 project settings file
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
-----
- 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 the 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 explicity set the WIA_DPS_PAGES to the number
of pages it requests or to the ALL_PAGES value.
- SelectDeviceDlg, DeviceDlg, idtGetData and idtGetBandedData API's
return S_FALSE if the user cancels, so it is not suffient to check the
return value with the SUCCEEDED() macro, the programmer must explicity
check S_FALSE. Similary, ReadMultiple and WriteMultiple API's return
S_FALSE whenthe function arguments are correct, but the function cannot
perform the requested operation, so the programmer must explicity
check the return value against S_FALSE.
- If the application wants to display a cancellable progress dialog,
it should display the dialog in separate thread. The data trasfer 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. So if the the progress
dialog is created in the same thread, the dialog (and the cancel button)
will be very sluggish to user input.
- The data trasfer can be cancelled only when BandedDataCallback returns and
since BandedDataCallback may be called every few seconds, the application
should indicate the user that the cancel operation is in progress, for
example it can disable the cancel button, or display a wait message.
