IWiaDevMgr
COM公式ドキュメント
アプリケーションは IWiaDevMgr インターフェイスを使用して、画像取り込みデバイスを作成および管理します。
解説(Remarks)
IWiaDevMgr インターフェイスは、すべての Component Object Model (COM) インターフェイスと同様に、IUnknown インターフェイスのメソッドを継承します。
| IUnknown のメソッド | 説明 |
|---|---|
| IUnknown::QueryInterface | サポートされているインターフェイスへのポインターを返します。 |
| IUnknown::AddRef | 参照カウントを増やします。 |
| IUnknown::Release | 参照カウントを減らします。 |
メソッド 9
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
アプリケーションは IWiaDevMgr::EnumDeviceInfo メソッドを使用して、利用可能な各 Windows Image Acquisition (WIA) デバイスのプロパティ情報を列挙します。
| lFlag | INT | in | 列挙する WIA デバイスの種類を指定します。WIA_DEVINFO_ENUM_LOCAL を設定してください。 |
| ppIEnum | IEnumWIA_DEV_INFO** | out | IEnumWIA_DEV_INFO インターフェイスへのポインターのアドレスを受け取ります。 |
戻り値
型: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
IWiaDevMgr::EnumDeviceInfo メソッドは、IEnumWIA_DEV_INFO インターフェイスをサポートする列挙子オブジェクトを作成します。IWiaDevMgr::EnumDeviceInfo は IEnumWIA_DEV_INFO インターフェイスへのポインターを ppIEnum パラメーターに格納します。アプリケーションは IEnumWIA_DEV_INFO インターフェイスポインターを使用して、ユーザーのコンピューターに接続されている各 WIA デバイスのプロパティを列挙できます。
アプリケーションは、ppIEnum パラメーターを通じて受け取ったインターフェイスポインターに対して IUnknown::Release メソッドを呼び出す必要があります。
IWiaDevMgr::CreateDevice は、Windows Image Acquisition (WIA) デバイス用の IWiaItem オブジェクトの階層ツリーを作成します。
| bstrDeviceID | LPWSTR | in | WIA デバイスの一意な識別子を指定します。 |
| ppWiaItemRoot | IWiaItem** | out | WIA デバイスの階層ツリーにおけるルートアイテムの IWiaItem インターフェイスへのポインターへのポインターです。 |
戻り値
型: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
アプリケーションは IWiaDevMgr::CreateDevice メソッドを使用して、bstrDeviceID パラメーターで指定された WIA デバイスのデバイスオブジェクトを作成します。
IWiaDevMgr::CreateDevice メソッドは、戻るときに ppWiaItemRoot パラメーターにポインターのアドレスを格納します。このポインターは、IWiaDevMgr::CreateDevice が作成した IWiaItem オブジェクトのツリーのルートアイテムを指します。アプリケーションはこのオブジェクトツリーを使用して、WIA デバイスを制御し、データを取得できます。
アプリケーションは、ppWiaItemRoot パラメーターを通じて受け取ったポインターに対して IUnknown::Release メソッドを呼び出す必要がある点に注意してください。
IWiaDevMgr::SelectDeviceDlg は、画像取り込み用のハードウェアデバイスをユーザーが選択できるダイアログボックスを表示します。
| hwndParent | HWND | in | デバイスの選択 ダイアログボックスを所有するウィンドウのハンドルです。 | ||||||
| lDeviceType | INT | in | 使用する WIA デバイスの種類を指定します。StiDeviceTypeDefault、StiDeviceTypeScanner、または StiDeviceTypeDigitalCamera を設定できます。 | ||||||
| lFlags | INT | in | ダイアログボックスの動作を指定します。次の値のいずれかを設定できます。
| ||||||
| pbstrDeviceID | LPWSTR* | inout | 出力時に、デバイスの識別子文字列を格納した文字列を受け取ります。入力時には、この情報が必要な場合はポインターのアドレスを渡し、不要な場合は NULL を渡します。 | ||||||
| ppItemRoot | IWiaItem** | out | 選択された WIA デバイスを表すツリーのルートアイテムの IWiaItem インターフェイスへのポインターのアドレスを受け取ります。デバイスが見つからない場合は NULL が格納されます。 |
戻り値
型: HRESULT
このメソッドは次の値を返します。
| 戻り値 | 意味 |
|---|---|
| S_OK | デバイスが正常に選択されました。 |
| S_FALSE | ユーザーがダイアログボックスをキャンセルしました。 |
| WIA_S_NO_DEVICE_AVAILABLE | lDeviceType パラメーターで指定された条件に一致する WIA ハードウェアデバイスがありません。 |
解説(Remarks)
このメソッドは デバイスの選択 ダイアログボックスを作成して表示し、ユーザーが画像取り込み用の WIA デバイスを選択できるようにします。デバイスが正常に選択されると、IWiaDevMgr::SelectDeviceDlg メソッドはそのデバイス用に IWiaItem オブジェクトの階層ツリーを作成します。そして、ルートアイテムの IWiaItem インターフェイスへのポインターを ppItemRoot パラメーターに格納します。
lDeviceType パラメーターでデバイスの種類を指定することで、特定の種類のデバイスのみをユーザーに表示できます。条件に一致するデバイスが 1 つだけの場合、IWiaDevMgr::SelectDeviceDlg は デバイスの選択 ダイアログボックスを表示しません。代わりに、そのデバイスの IWiaItem ツリーを作成し、ルートアイテムの IWiaItem インターフェイスへのポインターを ppItemRoot パラメーターに格納します。lFlags パラメーターに WIA_SELECT_DEVICE_NODEFAULT を渡すことでこの動作をオーバーライドし、IWiaDevMgr::SelectDeviceDlg に デバイスの選択 ダイアログボックスを強制的に表示させることができます。
条件に一致する WIA デバイスが複数ある場合は、一致するすべてのデバイスが デバイスの選択 ダイアログボックスに表示され、ユーザーが 1 つを選択できます。
アプリケーションは、ppItemRoot パラメーターを通じて受け取ったインターフェイスポインターに対して IUnknown::Release メソッドを呼び出す必要があります。
アプリケーションでは、デバイスと画像の選択を ファイル メニューの スキャナーまたはカメラから というメニュー項目から利用できるようにすることを推奨します。
IWiaDevMgr::SelectDeviceDlgID メソッドは、画像取り込み用のハードウェアデバイスをユーザーが選択できるダイアログボックスを表示します。
| hwndParent | HWND | in | デバイスの選択 ダイアログボックスを所有するウィンドウのハンドルです。 | ||||||
| lDeviceType | INT | in | 使用する WIA デバイスの種類を指定します。StiDeviceTypeDefault、StiDeviceTypeScanner、または StiDeviceTypeDigitalCamera を設定できます。 | ||||||
| lFlags | INT | in | ダイアログボックスの動作を指定します。次の値のいずれかを設定できます。
| ||||||
| pbstrDeviceID | LPWSTR* | inout | デバイスの識別子文字列を受け取る文字列へのポインターです。 |
戻り値
型: HRESULT
このメソッドは次の値を返します。
| 戻り値 | 意味 |
|---|---|
| S_OK | デバイスが正常に選択されました。 |
| S_FALSE | ユーザーがダイアログボックスをキャンセルしました。 |
| WIA_S_NO_DEVICE_AVAILABLE | 指定された条件に一致する WIA ハードウェアデバイスが、ユーザーのコンピューターに接続されていません。 |
解説(Remarks)
このメソッドは IWiaDevMgr::SelectDeviceDlg と同様に動作します。主な違いは、一致するデバイスが見つかっても、そのデバイス用に IWiaItem オブジェクトの階層ツリーを作成しない点です。
IWiaDevMgr::SelectDeviceDlg と同様に、IWiaDevMgr::SelectDeviceDlgID メソッドは デバイスの選択 ダイアログボックスを作成して表示します。これにより、ユーザーは画像取り込み用の WIA デバイスを選択できます。デバイスが正常に選択されると、IWiaDevMgr::SelectDeviceDlgID メソッドは pbstrDeviceID パラメーターを通じてその識別子文字列をアプリケーションに渡します。
lDeviceType パラメーターでデバイスの種類を指定することで、特定の種類のデバイスのみをユーザーに表示できます。条件に一致するデバイスが 1 つだけの場合、IWiaDevMgr::SelectDeviceDlgID は デバイスの選択 ダイアログボックスを表示しません。代わりに、ダイアログボックスを表示せずにデバイスの識別子文字列をアプリケーションに渡します。lFlags パラメーターに WIA_SELECT_DEVICE_NODEFAULT を渡すことでこの動作をオーバーライドし、IWiaDevMgr::SelectDeviceDlgID に デバイスの選択 ダイアログボックスを強制的に表示させることができます。
条件に一致する WIA デバイスが複数ある場合は、一致するすべてのデバイスが デバイスの選択 ダイアログボックスに表示され、ユーザーが 1 つを選択できます。
アプリケーションでは、デバイスと画像の選択を ファイル メニューの スキャナーまたはカメラから というメニュー項目から利用できるようにすることを推奨します。
IWiaDevMgr::GetImageDlg メソッドは、Windows Image Acquisition (WIA) デバイスから画像を取り込み、指定したファイルに書き込むための 1 つ以上のダイアログボックスを表示します。
| hwndParent | HWND | in | 画像の取得 ダイアログボックスを所有するウィンドウのハンドルです。 | ||||||||||
| lDeviceType | INT | in | 使用する WIA デバイスの種類を指定します。StiDeviceTypeDefault、StiDeviceTypeScanner、または StiDeviceTypeDigitalCamera を設定します。 | ||||||||||
| lFlags | INT | in | ダイアログボックスの動作を指定します。次の値を設定できます。
| ||||||||||
| lIntent | INT | in | 画像が表すことを意図しているデータの種類を指定します。イメージインテント値の一覧については、Image Intent Constants を参照してください。 | ||||||||||
| pItemRoot | IWiaItem* | in | IWiaDevMgr::CreateDevice が返した IWiaItem オブジェクトの階層ツリーのインターフェイスへのポインターです。 | ||||||||||
| bstrFilename | LPWSTR | in | 画像データの書き込み先ファイルの名前を指定します。 | ||||||||||
| pguidFormat | GUID* | inout | 入力時には、使用する形式を指定する GUID へのポインターを格納します。出力時には、使用された形式が格納されます。既定の形式を使用するには IID_NULL を渡します。 |
戻り値
型: HRESULT
IWiaDevMgr::GetImageDlg は、ユーザーがデバイス選択ダイアログボックスまたは画像取り込みダイアログボックスをキャンセルした場合は S_FALSE を、現在利用可能な WIA デバイスがない場合は WIA_S_NO_DEVICE_AVAILABLE を、利用可能な UI がない場合は E_NOTIMPL を、データ転送が正常に行われた場合は S_OK を返します。
IWiaDevMgr::GetImageDlg は、上記以外の理由で失敗した場合、Error Codes に規定された値、または標準の COM エラーを返します。
解説(Remarks)
このメソッドを呼び出すと、ユーザーが画像を取り込めるダイアログボックスが表示されます。また、IWiaDevMgr::SelectDeviceDlg メソッドが作成する デバイスの選択 ダイアログボックスを表示することもあります。
アプリケーションが pItemRoot パラメーターの値として NULL を渡した場合、IWiaDevMgr::GetImageDlg は デバイスの選択 ダイアログボックスを表示し、ユーザーが WIA 入力デバイスを選択できるようにします。アプリケーションが pItemRoot パラメーターを通じてデバイスのアイテムツリーへのポインターを渡して WIA 入力デバイスを指定した場合、IWiaDevMgr::GetImageDlg は デバイスの選択 ダイアログボックスを表示しません。代わりに、指定された入力デバイスを使用して画像を取り込みます。
デバイスの選択 ダイアログボックスを使用する場合、アプリケーションは WIA 入力デバイスの種類を指定できます。そのためには、pItemRoot パラメーターを NULL に設定し、適切な定数を lDeviceType パラメーターに渡す必要があります。指定された種類のデバイスが複数存在する場合、IWiaDevMgr::GetImageDlg は デバイスの選択 ダイアログボックスを表示し、使用するデバイスをユーザーが選択できるようにします。
IWiaDevMgr::GetImageDlg が一致するデバイスを 1 つだけ見つけた場合、デバイスの選択 ダイアログボックスは表示されません。代わりに、その一致するデバイスが選択されます。lFlags パラメーターに WIA_SELECT_DEVICE_NODEFAULT を渡すことでこの動作をオーバーライドし、IWiaDevMgr::GetImageDlg に デバイスの選択 ダイアログボックスを強制的に表示させることができます。
アプリケーションでは、デバイスと画像の選択を ファイル メニューの スキャナーまたはカメラから というメニュー項目から利用できるようにすることを推奨します。
ダイアログは、bstrFilename のフォルダーに対して、一意のファイル名でファイルを保存できるだけの十分な権限を持っている必要があります。また、そのフォルダーはユーザーデータを含むため、アクセス制御リスト (ACL) で保護する必要があります。
IWiaDevMgr::RegisterEventCallbackProgram メソッドは、デバイスイベントを受け取るアプリケーションを登録します。これは主に、WIA 向けに作成されていないアプリケーションとの下位互換性のために提供されています。
| lFlags | INT | in | 登録フラグを指定します。次の値を設定できます。
| ||||||||
| bstrDeviceID | LPWSTR | in | デバイス識別子を指定します。すべての WIA デバイスでイベントを登録するには NULL を渡します。 | ||||||||
| pEventGUID | GUID* | in | アプリケーションが登録するイベントを指定します。有効なイベント GUID の一覧については、WIA Event Identifiers を参照してください。 | ||||||||
| bstrCommandline | LPWSTR | in | アプリケーションを起動するために必要な完全パス名と適切なコマンドライン引数を含む文字列を指定します。引用符は 2 組使用する必要があります。例: ""C:\Program Files\MyExe.exe" /arg1"。 | ||||||||
| bstrName | LPWSTR | in | アプリケーションの名前を指定します。この名前は、複数のアプリケーションが同じイベントに登録している場合にユーザーに表示されます。 | ||||||||
| bstrDescription | LPWSTR | in | アプリケーションの説明を指定します。この説明は、複数のアプリケーションが同じイベントに登録している場合にユーザーに表示されます。 | ||||||||
| bstrIcon | LPWSTR | in | アプリケーションを表すアイコンを指定します。このアイコンは、複数のアプリケーションが同じイベントに登録している場合にユーザーに表示されます。文字列には、アプリケーションの名前と、アイコンの 0 から始まるインデックス (アプリケーションを表すアイコンが複数存在する場合があります) を、カンマで区切って指定します。例: "MyApp, 0"。 |
戻り値
型: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
WIA_ACTION_EVENT 型のハードウェアデバイスイベントを登録するには、IWiaDevMgr::RegisterEventCallbackProgram を使用します。アプリケーションが登録しているイベントが発生すると、そのアプリケーションが起動され、イベント情報がアプリケーションに送信されます。
アプリケーションは EnumRegisterEventInfo メソッドを使用して、イベント登録プロパティの列挙子オブジェクトへのポインターを取得します。
イベントがアクション型か通知型か (あるいはその両方か) は、イベント列挙によって返される WIA_DEV_CAP 構造体の ulFlags の値を調べることで判別できます。
プログラムは、WIA アーキテクチャ向けに作成されていないアプリケーションとの下位互換性のためにのみ IWiaDevMgr::RegisterEventCallbackProgram メソッドを使用してください。新しいアプリケーションでは、WIA アーキテクチャが提供する Component Object Model (COM) インターフェイスを使用してください。具体的には、デバイスイベントを登録するために IWiaDevMgr::RegisterEventCallbackInterface または IWiaDevMgr::RegisterEventCallbackCLSID を呼び出してください。
通常、このメソッドはインストールプログラムまたはスクリプトから呼び出されます。インストールプログラムまたはスクリプトが、WIA デバイスイベントを受け取るアプリケーションを登録します。イベントが発生すると、WIA ランタイムシステムによってアプリケーションが起動されます。
IWiaDevMgr::RegisterEventCallbackInterface メソッドは、実行中のアプリケーションを Windows Image Acquisition (WIA) イベント通知に登録します。
| lFlags | INT | in | 現在は使用されていません。0 を設定してください。 |
| bstrDeviceID | LPWSTR | in | デバイス識別子を指定します。すべての WIA デバイスでイベントを登録するには NULL を渡します。 |
| pEventGUID | GUID* | in | アプリケーションが登録するイベントを指定します。標準イベントの一覧については、WIA Event Identifiers を参照してください。 |
| pIWiaEventCallback | IWiaEventCallback* | in | WIA システムがイベント通知の送信に使用する IWiaEventCallback インターフェイスへのポインターです。 |
| pEventObject | IUnknown** | out | IUnknown インターフェイスへのポインターのアドレスを受け取ります。 |
戻り値
型: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
アプリケーションは EnumRegisterEventInfo メソッドを使用して、イベント登録プロパティの列挙子オブジェクトへのポインターを取得します。
イベントがアクション型か通知型か (あるいはその両方か) は、イベント列挙によって返される WIA_DEV_CAP 構造体の ulFlags の値を調べることで判別できます。
アプリケーションは、pEventObject パラメーターを通じて返された IUnknown ポインターを使用して IUnknown::Release メソッドを呼び出すことで、イベントの登録を解除できます。
IWiaDevMgr::RegisterEventCallbackCLSID メソッドは、アプリケーションが実行されていない場合でもイベントを受け取れるように、アプリケーションを登録します。
| lFlags | INT | in | 登録フラグを指定します。次の値を設定できます。
| ||||||||
| bstrDeviceID | LPWSTR | in | デバイス識別子を指定します。すべての WIA デバイスでイベントを登録するには NULL を渡します。 | ||||||||
| pEventGUID | GUID* | in | アプリケーションが登録するイベントを指定します。標準イベントの一覧については、WIA Event Identifiers を参照してください。 | ||||||||
| pClsID | GUID* | in | アプリケーションのクラス ID (CLSID) へのポインターです。WIA ランタイムシステムは、登録されたイベントが発生したときに、アプリケーションの CLSID を使用してアプリケーションを起動します。 | ||||||||
| bstrName | LPWSTR | in | イベントを登録するアプリケーションの名前を指定します。 | ||||||||
| bstrDescription | LPWSTR | in | イベントを登録するアプリケーションのテキストによる説明を指定します。 | ||||||||
| bstrIcon | LPWSTR | in | イベントを登録するアプリケーションのアイコンとして使用する画像ファイルの名前を指定します。 |
戻り値
型: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
WIA アプリケーションは、このメソッドを使用して WIA_ACTION_EVENT 型のハードウェアデバイスイベントを受け取るための登録を行います。プログラムが IWiaDevMgr::RegisterEventCallbackCLSID を呼び出すと、実行されていない場合でも WIA デバイスイベントを受け取るよう登録されます。
イベントが発生すると、WIA システムはどのアプリケーションがそのイベントを受け取るよう登録されているかを判別します。そして、CoCreateInstance 関数と pClsID パラメーターで指定されたクラス ID を使用してアプリケーションのインスタンスを作成します。次に、アプリケーションの ImageEventCallback メソッドを呼び出してイベント情報を送信します。
アプリケーションは EnumRegisterEventInfo メソッドを呼び出して、イベント登録情報を列挙できます。
イベントがアクション型か通知型か (あるいはその両方か) は、イベント列挙によって返される WIA_DEV_CAP 構造体の ulFlags の値を調べることで判別できます。
アプリケーションが登録済みの Component Object Model (COM) コンポーネントではなく、WIA アーキテクチャと互換性がない場合、開発者はこのメソッドの代わりに IWiaDevMgr::RegisterEventCallbackProgram を使用してください。
このメソッドは実装されていません。(IWiaDevMgr.AddDeviceDlg)
| hwndParent | HWND | in | |
| lFlags | INT | in |
戻り値
型: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IWiaDevMgr "{5EB2502A-8CF1-11D1-BF92-0060081ED811}" #usecom global IWiaDevMgr IID_IWiaDevMgr "{A1F4E726-8CF1-11D1-BF92-0060081ED811}" #comfunc global IWiaDevMgr_EnumDeviceInfo 3 int,sptr #comfunc global IWiaDevMgr_CreateDevice 4 wstr,sptr #comfunc global IWiaDevMgr_SelectDeviceDlg 5 sptr,int,int,var,sptr #comfunc global IWiaDevMgr_SelectDeviceDlgID 6 sptr,int,int,var #comfunc global IWiaDevMgr_GetImageDlg 7 sptr,int,int,int,sptr,wstr,var #comfunc global IWiaDevMgr_RegisterEventCallbackProgram 8 int,wstr,var,wstr,wstr,wstr,wstr #comfunc global IWiaDevMgr_RegisterEventCallbackInterface 9 int,wstr,var,sptr,sptr #comfunc global IWiaDevMgr_RegisterEventCallbackCLSID 10 int,wstr,var,var,wstr,wstr,wstr #comfunc global IWiaDevMgr_AddDeviceDlg 11 sptr,int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IWiaDevMgr "{5EB2502A-8CF1-11D1-BF92-0060081ED811}" #usecom global IWiaDevMgr IID_IWiaDevMgr "{A1F4E726-8CF1-11D1-BF92-0060081ED811}" #comfunc global IWiaDevMgr_EnumDeviceInfo 3 int,sptr #comfunc global IWiaDevMgr_CreateDevice 4 wstr,sptr #comfunc global IWiaDevMgr_SelectDeviceDlg 5 sptr,int,int,sptr,sptr #comfunc global IWiaDevMgr_SelectDeviceDlgID 6 sptr,int,int,sptr #comfunc global IWiaDevMgr_GetImageDlg 7 sptr,int,int,int,sptr,wstr,sptr #comfunc global IWiaDevMgr_RegisterEventCallbackProgram 8 int,wstr,sptr,wstr,wstr,wstr,wstr #comfunc global IWiaDevMgr_RegisterEventCallbackInterface 9 int,wstr,sptr,sptr,sptr #comfunc global IWiaDevMgr_RegisterEventCallbackCLSID 10 int,wstr,sptr,sptr,wstr,wstr,wstr #comfunc global IWiaDevMgr_AddDeviceDlg 11 sptr,int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。