GetImage
Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
parent directory.. | ||||
<!--TO READ THIS HELP FILE, RIGHT-CLICK ON THE FILE NAME IN THE
SOLUTION EXPLORER PANE AND SELECT "VIEW IN BROWSER"-->
<html><head><title>GetImage Sample: Demonstrates the Windows Image Acquisition API</title></head><body><h1>GetImage Sample: Demonstrates the Windows Image Acquisition API</h1><div id="mainSection"><div id="mainBody"><div id="allHistory" class="saveHistory" onsave="saveAll()" onload="loadAll()"></div><p /><p>The GetImage sample demonstrates the Windows Image Acquisition (WIA) application programming interfaces (APIs).</p><p>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.</p><p>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.</p><div class="alert"><table width="100%" cellspacing="0" cellpadding="0"><tr><th align="left">Security Note </th></tr><tr><td><p>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.</p></td></tr></table></div><h1 class="heading">Requirements</h1><div id="requirementsSection" class="section"><p>This sample can only be run on Windows XP and later.</p><p>The Microsoft Platform SDK must be installed.</p></div><h1 class="heading">Building and Running the Sample</h1><div id="sectionSection0" class="seeAlsoNoToggleSection"><h4 class="subHeading">To build and run this sample</h4><div class="subSection"><ol><li><p>In Visual Studio, load the solution GetImage.sln. </p></li><li><p>In Solution Explorer, right-click the project and click <b>Properties</b>. Set the following properties: </p><ul><li><p><b>C++</b> folder, <b>General</b> property page: modify the <b>Additional Include Directories</b> property to add the directory which contains the Platform SDK header files (for example, c:\Microsoft Platform SDK\include).</p></li><li><p><b>Linker</b> folder, <b>General</b> property page: modify the <b>Additional Library Directories</b> property to add the directory which contains the Platform SDK library files (for example, c:\Microsoft Platform SDK\lib). </p></li></ul></li><li><p>From the <b>Build</b> menu, click <b>Build</b>. </p></li><li><p>From the <b>Debug</b> menu, click <b>Start Without Debugging</b>.</p></li></ol></div><p>The sample application has a single command on its <b>File</b> menu, named <b>From scanner or camera</b>. 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). </p></div><h1 class="heading">Files in the Sample</h1><div id="sectionSection1" class="seeAlsoNoToggleSection"><h3 class="subHeading"></h3><div class="tableSection"><table width="100%" cellspacing="2" cellpadding="5"><tr><th>
File
</th><th>
Description
</th></tr><tr><td><p>WiaWrap.cpp</p></td><td><p>Contains wrapper functions for simpler WIA operations</p></td></tr><tr><td><p>WiaWrap.h</p></td><td><p>Header file for WiaWrap.cpp</p></td></tr><tr><td><p>EventCallback.cpp</p></td><td><p>Implements the callback function for WIA device events</p></td></tr><tr><td><p>EventCallback.h</p></td><td><p>Header file for EventCallback.cpp</p></td></tr><tr><td><p>DataCallback.cpp</p></td><td><p>Implements the callback function for data transfers</p></td></tr><tr><td><p>DataCallback.h</p></td><td><p>Header file for DataCallback.cpp</p></td></tr><tr><td><p>BitmapUtil.cpp</p></td><td><p>Contains device independent bitmap (DIB) functions</p></td></tr><tr><td><p>BitmapUtil.h</p></td><td><p>Header file for BitmapUtil.cpp</p></td></tr><tr><td><p>ProgressDlg.cpp</p></td><td><p>Implements a simple progress dialog</p></td></tr><tr><td><p>ProgressDlg.h</p></td><td><p>Header file for ProgressDlg.cpp</p></td></tr><tr><td><p>GetImage.cpp</p></td><td><p>Implements the main entry point for the application</p></td></tr><tr><td><p>GetImage.rc</p></td><td><p>Contains the project resources</p></td></tr><tr><td><p>resource.h</p></td><td><p>Header file for the resource identifiers</p></td></tr><tr><td><p>MainWnd.cpp</p></td><td><p>Implements the main frame window</p></td></tr><tr><td><p>MainWnd.h</p></td><td><p>Header file for MainWnd.cpp</p></td></tr><tr><td><p>BitmapWnd.cpp</p></td><td><p>Implements an image display window</p></td></tr><tr><td><p>BitmapWnd.h</p></td><td><p>Header file for BitmapWnd.cpp</p></td></tr><tr><td><p>StdAfx.cpp</p></td><td><p>Precompiled headers file</p></td></tr><tr><td><p>StdAfx.h</p></td><td><p>Includes frequently used standard system files</p></td></tr></table></div></div><h1 class="heading">Notes on Programming with the WIA API</h1><div id="sectionSection2" class="seeAlsoNoToggleSection"><p>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. </p><p>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. </p><p>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.</p><p>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.</p><p>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.</p><p>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.</p><p>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.</p></div><h1 class="heading">Keywords</h1><div id="sectionSection3" class="seeAlsoNoToggleSection"><p>This sample demonstrates the following keywords:</p><p>IWiaDevMgr, IWiaDevMgr::SelectDeviceDlg, IWiaEventCallback, IWiaEventCallback::ImageEventCallback, IWiaItem, IWiaItem::DeviceDlg, IWiaPropertyStorage, IWiaPropertyStorage::ReadMultiple, IWiaPropertyStorage::WriteMultiple, IWiaDataTransfer, IWiaDataTransfer::idtGetBandedData, IWiaDataCallback, IWiaDataCallback::BandedDataCallback</p></div></div><div id="footer"><div class="footerLine"></div>
© Microsoft Corporation. All rights reserved. Send <a href="mailto:[email protected]?subject=Documentation Feedback :GetImage Sample: Demonstrates the Windows Image Acquisition API">comments</a> about this topic to Microsoft.
</div></div></body></html>