GetImage サンプル : Windows Image Acquisition API の例
更新 : 2007 年 11 月
GetImage サンプルでは、WIA (Windows Image Acquisition) アプリケーション プログラミング インターフェイス (API: Application Programming Interface) の例を示します。
WIA API のセットにはファイル転送に必要な単純な API が含まれますが、インメモリ転送に必要な単純な API 呼び出しはありません。GetImage は WiaGetImage という名前のラッパー関数を実装し、SelectDeviceDlg、DeviceDlg、idtGetBandedData の各 API の機能を組み合わせて、イメージの取得を 1 つの関数呼び出し内に完全にカプセル化します。
このサンプルは、コード自体が主な機能となっています。WiaWrap、EventCallback、DataCallback、BitmapUtil、ProgressDlg の各ファイルは、インメモリ イメージ転送の正しい実装方法を示します。この概要の後半にある「WIA API を使用したプログラミングに関する注意事項」セクションでは、WIA アプリケーション作成時の共通の落とし穴について詳しく説明し、サンプルにはその処理方法を示します。このサンプルを参照用として読み込むか、またはサンプル コードをライブラリとして直接使用できます。各関数の使い方については、ヘッダー ファイルのコメントで詳しく説明しています。
.gif "セキュリティに関するメモ") セキュリティに関するメモ : |
|---|
このサンプル コードは概念を示す目的で提供されているものです。必ずしも最も安全なコーディング手法に従っているわけではないので、アプリケーションまたは Web サイトでは使用しないでください。Microsoft は、サンプル コードが意図しない目的で使用された場合に、付随的または間接的な損害について責任を負いません。 |
サンプルとそのインストール手順を取得するには
Visual Studio で、[ヘルプ] メニューの [サンプル] をクリックします。
詳細については、「サンプル ファイルの格納場所」を参照してください。
使用できるサンプルの最新バージョンと完全な一覧については、オンラインの Visual Studio 2008 Samples のページを参照してください。
サンプルは、コンピュータのハード ディスク上にもあります。既定では、サンプルおよび Readme ファイルは、\Program Files\Visual Studio 9.0\Samples\ の下のフォルダにコピーされます。Visual Studio Express Edition の場合、すべてのサンプルはオンライン上にあります。
必要条件
このサンプルを実行できるのは、Windows XP 以降です。
また、Microsoft Windows SDK をインストールしている必要があります。
サンプルのビルドと実行
このサンプルをビルドして実行するには
Visual Studio で、ソリューション GetImage.sln を読み込みます。
ソリューション エクスプローラで、プロジェクトを右クリックし、[プロパティ] をクリックします。次のプロパティを設定します。
[全般] プロパティ ページ ([C++] フォルダ) : [追加のインクルード ディレクトリ] プロパティを変更して、Windows SDK のヘッダー ファイルを含むディレクトリ (c:\Microsoft Windows SDK\include など) を追加します。
[全般] プロパティ ページ ([リンカ] フォルダ) : [追加のライブラリ ディレクトリ] プロパティを変更して、Windows SDK のライブラリ ファイルを含むディレクトリ (c:\Microsoft Windows SDK\lib など) を追加します。
[ビルド] メニューの [ビルド] をクリックします。
[デバッグ] メニューの [デバッグなしで開始] をクリックします。
サンプル アプリケーションの [File] メニューには、[From scanner or camera] という名前のコマンドが 1 つあります。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: Device Independent Bitmap) 関数が含まれます。 |
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 (Automatic Document Feeder) で DeviceDlg API を使用する場合、API は ADF を 1 ページ分スキャンするように設定します。複数のページをスキャンする場合は、アプリケーションで WIA_DPS_PAGES を必要なページ数または ALL_PAGES 値に明示的に設定する必要があります。
ユーザーがキャンセルした場合は、SelectDeviceDlg、DeviceDlg、idtGetData、idtGetBandedData の各 API から S_FALSE が返されます。この場合、SUCCEEDED マクロを使用して戻り値をチェックするだけでは不十分です。プログラマが S_FALSE を明示的にチェックする必要があります。同様に、関数の引数が正しい場合には ReadMultiple と WriteMultiple の各 API から S_FALSE が返されますが、その関数は要求された操作を実行できません。この場合、プログラマは S_FALSE に対する戻り値を明示的にチェックする必要があります。
キャンセルできるプログレス ダイアログ ボックスをアプリケーションで表示する場合は、そのダイアログ ボックスを別のスレッドに表示する必要があります。データ転送スレッドは転送が完了するまでブロックされるため、到着したウィンドウ メッセージはすぐに処理できません。同じスレッドで作成されたプログレス ダイアログ ボックスおよびその [Cancel] ボタンは、ユーザーの入力に対する反応が遅くなります。
データ転送をキャンセルできるのは、BandedDataCallback が戻るときだけです。BandedDataCallback は数秒単位で呼び出されることがあるため、アプリケーションではキャンセル操作が実行中であることをユーザーに対して示す必要があります。たとえば、[Cancel] ボタンを無効にしたり、待機メッセージを表示したりできます。
キーワード
このサンプルでは、次のキーワードを使用します。
IWiaDevMgr、IWiaDevMgr::SelectDeviceDlg、IWiaEventCallback、IWiaEventCallback::ImageEventCallback、IWiaItem、IWiaItem::DeviceDlg、IWiaPropertyStorage、IWiaPropertyStorage::ReadMultiple、IWiaPropertyStorage::WriteMultiple、IWiaDataTransfer、IWiaDataTransfer::idtGetBandedData、IWiaDataCallback、IWiaDataCallback::BandedDataCallback