Образец GetImage: демонстрация API-интерфейса службы загрузки изображений Windows
Обновлен: Ноябрь 2007
В образце GetImage показаны прикладные программные интерфейсы (API) службы загрузки изображений (WIA).
Набор API-интерфейсов WIA содержит простые API-интерфейсы для передачи файлов, однако для передачи данных, находящихся в памяти, отсутствует возможность простого вызова API. Образец GetImage реализуют функцию-оболочку с именем WiaGetImage, в которой объединяются возможности API SelectDeviceDlg, DeviceDlg и idtGetBandedData, что позволяет полностью инкапсулировать загрузку изображений в одном вызове функции.
Главной отличительной особенностью образца является сам программный код. Файлы WiaWrap, EventCallback, DataCallback, BitmapUtil и ProgressDlg показывают правильный способ реализации передачи изображений, находящихся в памяти. Далее в подразделе "Замечания о программировании API-интерфейса WIA" этого краткого описания показаны распространенные сложные ситуации, которые встречаются в процессе создания приложения WIA, и в образце показано, как их разрешить. Этот образец может случить справочником по написанию кода или использоваться непосредственно, в виде библиотеки. Использование каждой функции подробно описано в комментариях в файле заголовка.
.gif "Примечание о безопасности") Примечание о безопасности. |
|---|
Этот образец кода служит для демонстрации основных принципов и не предназначен для использования в приложениях или на веб-узлах, поскольку не может считаться примером наиболее безопасного кода. Корпорация Майкрософт не несет ответственности за случайные или косвенные убытки в случае использования образца кода не по назначению. |
Чтобы получить образцы и инструкции по их установке, выполните следующие действия.
В меню Справка среды Visual Studio выберите пункт Примеры.
Дополнительные сведения см. в разделе Поиск файлов примеров.
Самая последняя версия и полный список образцов доступны в Интернете на странице образцов Visual Studio 2008.
Кроме того, образцы находятся на жестком диске компьютера. По умолчанию образцы кода и файл Readme копируются в папку, находящуюся в папке \Program Files\Visual Studio 9.0\Samples\. Все образцы кода для экспресс-выпусков Visual Studio находятся в Интернете.
Требования
Этот образец может запускать только в Windows XP или более поздней версии ОС.
Необходимо установить Microsoft SDK для Windows.
Построение и запуск образца
Построение и запуск этого образца
Загрузите в Visual Studio решение GetImage.sln.
В обозревателе решений щелкните правой кнопкой мыши проект и выберите пункт Свойства. Задайте следующие свойства:
Папка C++, страница свойств Общие: измените свойство Дополнительные каталоги включения, добавив каталог, содержащий файлы заголовка SDK для Windows (например, c:\Microsoft SDK для Windows\include).
Папка Компоновщик, страница свойств Общие: измените свойство Дополнительные каталоги библиотек, добавив каталог, содержащий файлы библиотеки SDK для Windows (например, c:\Microsoft SDK для Windows\lib).
В меню Построение выберите команду Построить.
В меню Отладка выберите команду Запуск без отладки.
Образец приложения содержит одну команду в меню 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 |
Включает часто используемые стандартные системные файлы |
Замечания о программировании API-интерфейса WIA
Рекомендуется, чтобы приложения позволяли выбирать устройства и изображения посредством команды меню "File" с именем "From Scanner or Camera..." Если в системе нет устройств WIA, эта команда будет недоступной.
Рекомендуется, чтобы разработчики проверяли создаваемые приложения с камерами, подключаемыми через последовательный порт или порт USB, а также с планшетными сканерами, сканерами с рулонной подачей и сканерами с автоматической подачей. Кроме того, для тестирования можно использовать программные эмуляторы устройств, доступные в пакете Windows DDK.
Сканеры с рулонной подачей обычно не обладают данными о высоте изображений на момент начала передачи данных, поэтому они могут возвращать значение 0 для размера страницы и для высоты изображения в заголовке файла растрового изображения. В этом случае функция обратного вызова должна иметь возможность расширения буфера, когда поступают новые данные, и должна явно вычислять высоту после завершения передачи.
Во время использования API DeviceDlg с устройством автоматической подачи, API-интерфейс настроит устройство подачи на сканирование одной страницы. Если нужно отсканировать несколько страниц, приложение должно явно задать в свойстве WIA_DPS_PAGES необходимое количество страниц или значение свойства ALL_PAGES.
API SelectDeviceDlg, DeviceDlg, idtGetData и idtGetBandedData возвращают значение S_FALSE, если пользователь отменяет операцию, поэтому для проверки возвращаемого значения недостаточно макроса SUCCEEDED. Программист должен явно проверить значение S_FALSE. Аналогично, API ReadMultiple и WriteMultiple возвращают значение 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