GetImage 示例：演示 Windows 图像获取 API

  • 项目

更新：2007 年 11 月

GetImage 示例说明 Windows 图像获取 (WIA) 应用程序编程接口 (API)。

WIA API 集包含用于文件传输的简单 API，但不包含用于内存中传输的简单 API 调用。GetImage 实现名为 WiaGetImage 的包装函数，它将 SelectDeviceDlg、DeviceDlg 和 idtGetBandedData API 的功能组合起来以完全将图像获取封装在单个函数调用内。

示例的主要功能是代码本身。WiaWrap、EventCallback、DataCallback、BitmapUtil 和 ProgressDlg 文件说明实现内存中图像传输的正确方式。本摘要后面的“WIA API 编程说明”一节着重介绍了在编写 WIA 应用程序时遇到的常见问题，同时还介绍了说明如何处理这些问题的示例。您可以作为参考阅读该示例或直接将示例代码用作库。在头文件注释中详细介绍了每一函数的用法。

安全说明：

提供该示例代码是为了阐释一个概念，并不代表着最安全的编码实践，因此不应在应用程序或网站中使用该示例代码。对于超出本示例代码的预期用途以外的使用所造成的偶然或继发性损失，Microsoft 不承担任何责任。

获取示例和安装示例的说明：

  • 在 Visual Studio 的“帮助”菜单上，单击“示例”。

    有关更多信息，请参见定位示例文件。

  • 示例的最新版本和完整列表可以从 Visual Studio 2008 Samples page（Visual Studio 2008 示例页面）联机获取。

  • 还可以在计算机的硬盘上查找示例。默认情况下，将示例和自述文件复制到 \Program Files\Visual Studio 9.0\Samples\ 下的文件夹中。对于 Visual Studio 速成版，所有示例都位于联机位置。

要求

该示例只能在 Windows XP 和更高版本上运行。

必须安装 Microsoft Windows SDK。

生成并运行示例

生成并运行此示例

  1. 在 Visual Studio 中，加载解决方案 GetImage.sln。

  2. 在解决方案资源管理器中，右击该项目并单击“属性”。设置下列属性：

    • C++ 文件夹，**“常规”属性页：修改“附加包含目录”**属性来添加包含 Windows SDK 头文件的目录（例如，c:\Microsoft Windows SDK\include）。

    • Linker 文件夹，**“常规”属性页：修改“附加库目录”**属性来添加包含 Windows SDK 库文件的目录（例如，c:\Microsoft Windows SDK\lib）。

  3. 从“生成”菜单中单击“生成”。

  4. 在“调试”菜单中，单击“开始执行（不调试）”。

示例应用程序在其“File”菜单上有一个命令，名为“From scanner or camera”。在连好 WIA 设备（或设备模拟器）后，该菜单项将启用。在用户选择该菜单命令后，该示例将按顺序显示“WIA Device Selection”对话框、“Image Selection”对话框和“Image Transfer”对话框。设备和图像选择对话框是系统提供的公共对话框，而传输对话框是在此示例中实现的。最后，该示例将在子窗口中显示传输的图像。

示例中的文件

文件

说明

WiaWrap.cpp

包含较为简单的 WIA 操作的包装函数

WiaWrap.h

WiaWrap.cpp 的头文件

EventCallback.cpp

实现用于 WIA 设备事件的回调函数

EventCallback.h

EventCallback.cpp 的头文件

DataCallback.cpp

实现用于数据传输的回调函数

DataCallback.h

DataCallback.cpp 的头文件

BitmapUtil.cpp

包含设备无关位图 (DIB) 函数

BitmapUtil.h

BitmapUtil.cpp 的头文件

ProgressDlg.cpp

实现简单进度对话框

ProgressDlg.h

ProgressDlg.cpp 的头文件

GetImage.cpp

实现应用程序的主入口点

GetImage.rc

包含项目资源

resource.h

资源标识符的头文件

MainWnd.cpp

实现主框架窗口

MainWnd.h

MainWnd.cpp 的头文件

BitmapWnd.cpp

实现图像显示窗口

BitmapWnd.h

BitmapWnd.cpp 的头文件

StdAfx.cpp

预编译头文件

StdAfx.h

包括常用标准系统文件

WIA API 编程说明

建议应用程序通过“File”菜单上的名为“From Scanner or Camera...”的菜单项提供设备和图像选择。如果系统上没有任何 WIA 设备，该项将变灰。

建议应用程序开发人员通过串口和 USB 相机以及平板、滚动馈送和 ADF 扫描仪测试其应用程序。此外，Windows DDK 上提供的纯软件设备模拟器可用于测试。

滚动馈送扫描仪在开始数据传输时通常不知道图像高度，因此它们在位图标头中对于图像大小和图像高度可能返回 0。在此情况下，回调函数应该能够在新数据到达时扩展其缓冲区，并且应该在传输完成后显式计算该高度。

当对自动文档送纸器 (ADF) 使用 DeviceDlg API 时，API 将 ADF 设置为扫描一页。如果需要多页，应用程序应将 WIA_DPS_PAGES 显式设置为其请求的页数或者 ALL_PAGES 值。

如果用户取消，则 SelectDeviceDlg、DeviceDlg、idtGetData 和 idtGetBandedData API 返回 S_FALSE，因此用 SUCCEEDED 宏检查返回值是不够的。程序员必须显式检查 S_FALSE。同样，当函数参数正确时，ReadMultiple 和 WriteMultiple API 返回 S_FALSE，但函数不能执行请求的操作，因此程序员必须根据 S_FALSE 显式检查返回值。

如果应用程序想要显示可被取消的进度对话框，它应在单独的线程中显示该对话框。数据传输线程在完成传输前将被阻塞，因此在窗口消息到达时它将不能及时处理这些消息。如果在同一个线程中创建进度对话框，对话框（和取消按钮）对用户输入的反应将非常迟缓。

只在 BandedDataCallback 返回时可以取消数据传输。因为每隔几秒钟就可能调用 BandedDataCallback，所以应用程序应指示用户取消操作正在进行中。例如，它可以禁用取消按钮，或者显示等待消息。

关键字

此示例说明以下关键字：

IWiaDevMgr、IWiaDevMgr::SelectDeviceDlg、IWiaEventCallback、IWiaEventCallback::ImageEventCallback、IWiaItem、IWiaItem::DeviceDlg、IWiaPropertyStorage、IWiaPropertyStorage::ReadMultiple、IWiaPropertyStorage::WriteMultiple、IWiaDataTransfer、IWiaDataTransfer::idtGetBandedData、IWiaDataCallback、IWiaDataCallback::BandedDataCallback

请参见

其他资源

Visual C++ 示例应用程序