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.

Security Note
This sample code is intended to illustrate a concept, and it shows only the code that is relevant to that concept. It may not meet the security requirements for a specific environment, and it should not be used exactly as shown. We recommend that you add security and error-handling code to make your projects more secure and robust. Microsoft provides this sample code "AS IS" with no warranties.

To get samples and instructions for installing them:

To access samples from Visual Studio

• On the Help menu, click Samples.

  By default, these samples are installed in drive:\Program Files\Microsoft Visual Studio 10.0\Samples\.

• For the most recent version of this sample and a list of other samples, see Visual Studio Samples on the MSDN Web site.

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

1. In Visual Studio, load the solution GetImage.sln.

2. 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 Library Directories property to add the directory which contains the Windows SDK library files (for example, c:\Microsoft Windows SDK\lib).

3. From the Build menu, click Build.

4. 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

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

See Also

Other Resources

Visual C++: Samples Included in Visual C++