# 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 provided to illustrate a concept and should not be used in applications or Web sites, as it may not illustrate the safest coding practices.

# Requirements

This sample can only be run on Windows XP and later.

The Microsoft Platform 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 Platform SDK header files (for example, c:\Microsoft Platform SDK\include).

   - Linker folder, General property page: modify the Additional Library Directories property to add the directory which contains the Platform SDK library files (for example, c:\Microsoft Platform 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

###

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