ホーム › Devices.ImageAcquisition › IWiaItem

IWiaItem

COM

IID4db1ad10-3391-11d2-9a33-00c04fa36145継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

各 Windows Image Acquisition (WIA) ハードウェアデバイスは、IWiaItem オブジェクトの階層ツリーとしてアプリケーションに提供されます。

解説(Remarks)

IWiaItem インターフェイスのメソッドの中には、デバイスのツリーのルートアイテムでのみ有効なものがあります。それ以外のメソッドはすべてのアイテムで有効です。メソッドは次のように分類されます。

ルートアイテムでのみ有効	IWiaItem::DeviceCommand
	IWiaItem::DeviceDlg
	IWiaItem::EnumDeviceCapabilities
	IWiaItem::EnumRegisterEventInfo
すべてのアイテムで有効	IWiaItem::AnalyzeItem
	IWiaItem::CreateChildItem
	IWiaItem::DeleteItem
	IWiaItem::EnumChildItems
	IWiaItem::FindItemByName
	IWiaItem::GetItemType
	IWiaItem::GetRootItem

IWiaItem インターフェイスは、他のすべての Component Object Model (COM) インターフェイスと同様に、IUnknown インターフェイスのメソッドを継承します。

IUnknown のメソッド	説明
IUnknown::QueryInterface	サポートされているインターフェイスへのポインターを返します。
IUnknown::AddRef	参照カウントをインクリメントします。
IUnknown::Release	参照カウントをデクリメントします。

メソッド 15

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT GetItemType(INT* pItemType)

IWiaItem::GetItemType メソッドは、アイテムの型情報を取得するためにアプリケーションから呼び出されます。

pItemType

INT*

out

WIA Item Type Flags の組み合わせを格納する LONG 変数のアドレスを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

Windows Image Acquisition (WIA) ハードウェアデバイスに関連付けられたオブジェクトの階層ツリー内の各 IWiaItem オブジェクトは、特定のデータ型を持ちます。アイテムオブジェクトはフォルダーとファイルを表します。フォルダーにはファイルオブジェクトが含まれます。ファイルオブジェクトには、画像やサウンドなど、デバイスが取得したデータが含まれます。このメソッドにより、アプリケーションはデバイス内のアイテムオブジェクトの階層ツリーにある任意のアイテムの型を識別できます。

アイテムは複数の型を持つ場合があります。たとえば、オーディオファイルを表すアイテムは、型属性 WiaItemTypeAudio | WiaItemTypeFile を持ちます。

vtbl 4 HRESULT AnalyzeItem(INT lFlags)

IWiaItem::AnalyzeItem メソッドは、Windows Image Acquisition (WIA) ハードウェアデバイスにデータを取得させ、どのデータ型が存在するかを検出させます。

lFlags

INT

現在使用されていません。ゼロを設定してください。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドは、ページ上にどのような型のデータがあるかを検出するために、スキャナーで使用されます。アプリケーションがこのメソッドを呼び出すと、WIA ハードウェアデバイスのドライバーが現在のページをスキャンして解析します。検出したデータ型ごとに、そのデータがページ上で占める領域を表す IWiaItem オブジェクトを作成します。

画像処理ソフトウェアや OCR ソフトウェアは、この機能を利用してページ上の図形やテキストを検出できます。このメソッドは、作成した領域を WIA デバイスの IWiaItem ツリーに追加します。アプリケーションは個々の領域を選択し、標準的なデータ転送メソッドを使用してそこからデータを取得できます。

必要に応じて、アプリケーションはこのメソッドが作成した領域をオーバーライドできます。

vtbl 5 HRESULT EnumChildItems(IEnumWiaItem** ppIEnumWiaItem)

IWiaItem::EnumChildItems メソッドは、Windows Image Acquisition (WIA) デバイスの IWiaItem ツリー内の空でないフォルダーに対して列挙子オブジェクトを作成し、その IEnumWiaItem インターフェイスへのポインターを返します。

ppIEnumWiaItem

IEnumWiaItem**

out

IWiaItem::EnumChildItems が作成する IEnumWiaItem インターフェイスへのポインターのアドレスを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

WIA ランタイムシステムは、各 WIA ハードウェアデバイスを IWiaItem オブジェクトの階層ツリーとして表します。IWiaItem::EnumChildItems メソッドを使用すると、アプリケーションは現在のアイテム内の子アイテムを列挙できます。ただし、このメソッドはフォルダーであるアイテムにのみ適用できます。

フォルダーが空でない場合、そのフォルダーには IWiaItem オブジェクトのサブツリーが含まれます。IWiaItem::EnumChildItems メソッドは、フォルダーに含まれるすべてのアイテムを列挙します。列挙子へのポインターは ppIEnumWiaItem パラメーターに格納されます。アプリケーションはこの列挙子ポインターを使用して、オブジェクトの子アイテムを列挙します。

アプリケーションは、ppIEnumWiaItem パラメーターを通じて受け取ったインターフェイスポインターに対して IUnknown::Release メソッドを呼び出す必要があります。

vtbl 6 HRESULT DeleteItem(INT lFlags)

IWiaItem::DeleteItem メソッドは、デバイスのオブジェクトツリーから現在の IWiaItem オブジェクトを削除します。

lFlags

INT

現在使用されていません。ゼロを設定してください。

戻り値

型: HRESULT

このメソッドは、削除されたアイテムの数にかかわらず S_OK を返します。メソッドが失敗した場合は、標準の COM エラーコードを返します。

解説(Remarks)

Windows Image Acquisition (WIA) ランタイムシステムは、ユーザーのコンピューターに接続された各 WIA ハードウェアデバイスを IWiaItem オブジェクトの階層ツリーとして表します。特定の WIA デバイスが、そのツリーから IWiaItem オブジェクトを削除することをアプリケーションに許可するかどうかはデバイスによって異なります。アイテム削除機能をサポートしているかどうかをデバイスに問い合わせるには、IEnumWIA_DEV_CAPS インターフェイスを使用します。

デバイスが IWiaItem ツリー内のアイテム削除をサポートしている場合は、IWiaItem::DeleteItem メソッドを呼び出して IWiaItem オブジェクトを削除します。なお、このメソッドは、そのオブジェクトへの参照がすべて解放された後にのみオブジェクトを削除します。

vtbl 7 HRESULT CreateChildItem(INT lFlags, LPWSTR bstrItemName, LPWSTR bstrFullItemName, IWiaItem** ppIWiaItem)

IWiaItem::CreateChildItem メソッドは、デバイスの IWiaItem ツリーに IWiaItem オブジェクトを追加するためにアプリケーションが使用します。

lFlags	INT	in	WIA アイテムの型を指定します。WIA Item Type Flags に列挙されている値のいずれかを設定する必要があります。
bstrItemName	LPWSTR	in	"Top" など、WIA アイテム名を指定します。このパラメーターはファイル名に相当するものと考えることができます。
bstrFullItemName	LPWSTR	in	WIA アイテムの完全な名前を指定します。このパラメーターは、"003\Root\Top" のようなファイルへのフルパスに相当するものと考えることができます。
ppIWiaItem	IWiaItem**	out	IWiaItem::CreateChildItem メソッドが設定する IWiaItem インターフェイスへのポインターのアドレスを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

一部の WIA ハードウェアデバイスは、そのデバイスを表す IWiaItem ツリーに新しいアイテムを作成することをアプリケーションに許可します。アプリケーションは、デバイスがこの機能をサポートしているかどうかを確認する必要があります。現在のデバイスの機能を列挙するには、IEnumWIA_DEV_CAPS インターフェイスを使用します。

デバイスが IWiaItem ツリーへの新しいアイテムの作成を許可している場合、IWiaItem::CreateChildItem を呼び出すと、現在のノードの子となる新しい IWiaItem が作成されます。IWiaItem::CreateChildItem は、新しいノードへのポインターを ppIWiaItem パラメーターを通じてアプリケーションに渡します。

アプリケーションは、ppIWiaItem パラメーターを通じて受け取ったインターフェイスポインターに対して IUnknown::Release メソッドを呼び出す必要があります。

vtbl 8 HRESULT EnumRegisterEventInfo(INT lFlags, GUID* pEventGUID, IEnumWIA_DEV_CAPS** ppIEnum)

IWiaItem::EnumRegisterEventInfo メソッドは、アプリケーションが登録しているイベントに関する情報を取得するための列挙子を作成します。

lFlags	INT	in	現在使用されていません。ゼロを設定してください。
pEventGUID	GUID*	in	登録情報を取得したいハードウェアイベントを指定する識別子へのポインターです。
ppIEnum	IEnumWIA_DEV_CAPS**	out	IEnumWIA_DEV_CAPS インターフェイスへのポインターのアドレスを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

アプリケーションは、イベント情報用の列挙子オブジェクトを作成するためにこのメソッドを呼び出します。IWiaItem::EnumRegisterEventInfo は、列挙子オブジェクトの IEnumWIA_DEV_CAPS インターフェイスのアドレスを ppIEnum パラメーターに格納します。プログラムはこのインターフェイスポインターを使用して、登録しているイベントのプロパティを列挙します。

各 WIA_DEV_CAP 構造体には、そのイベントが WIA_NOTIFICATION_EVENT 型か WIA_ACTION_EVENT 型か、あるいはその両方かを示す情報が含まれます。

アプリケーションは、ppIEnum パラメーターを通じて受け取ったインターフェイスポインターに対して IUnknown::Release メソッドを呼び出す必要があります。

vtbl 9 HRESULT FindItemByName(INT lFlags, LPWSTR bstrFullItemName, IWiaItem** ppIWiaItem)

IWiaItem::FindItemByName メソッドは、名前を検索キーとしてアイテムのサブアイテムのツリーを検索します。各 IWiaItem オブジェクトは、標準プロパティの 1 つとして名前を持ちます。

lFlags	INT	in	現在使用されていません。ゼロを設定してください。
bstrFullItemName	LPWSTR	in	検索対象のアイテムの名前を指定します。
ppIWiaItem	IWiaItem**	out	IWiaItem インターフェイスへのポインターです。

戻り値

型: HRESULT

このメソッドは、アイテムが見つかった場合は S_OK を、見つからなかった場合は S_FALSE を返します。メソッドが失敗した場合は、標準の COM エラーコードを返します。

解説(Remarks)

このメソッドは、名前を検索キーとして現在のアイテムのサブアイテムのツリーを検索します。IWiaItem::FindItemByName が bstrFullItemName で指定されたアイテムを見つけた場合、そのアイテムの IWiaItem インターフェイスへのポインターのアドレスを ppIWiaItem パラメーターに格納します。

vtbl 10 HRESULT DeviceDlg(HWND hwndParent, INT lFlags, INT lIntent, INT* plItemCount, IWiaItem*** ppIWiaItem)

IWiaItem::DeviceDlg メソッドは、画像取り込みの準備のためにユーザーへダイアログボックスを表示する目的でアプリケーションが使用します。

hwndParent

HWND

ダイアログボックスの親ウィンドウのハンドルです。

lFlags

INT

ダイアログボックスの動作を制御するフラグのセットを指定します。次の値のいずれかを設定できます。

フラグ	意味
0	既定の動作。
WIA_DEVICE_DIALOG_SINGLE_IMAGE	デバイスの画像取り込みダイアログボックスでの画像選択を 1 枚のみに制限します。
WIA_DEVICE_DIALOG_USE_COMMON_UI	ベンダー提供の UI ではなく、システム UI が利用可能であればそれを使用します。システム UI が利用できない場合はベンダー UI が使用されます。いずれの UI も利用できない場合、この関数は E_NOTIMPL を返します。

lIntent

INT

その画像がどのような種類のデータを表すことを意図しているかを指定します。画像インテント値の一覧については、Image Intent Constants を参照してください。

メモこのメソッドは、すべての WIA_INTENT_IMAGE_* 画像インテントを無視します。

plItemCount

INT*

inout

ppIWiaItem パラメーターが示す配列内のアイテム数を受け取ります。

ppIWiaItem

IWiaItem***

inout

IWiaItem インターフェイスへのポインターの配列のアドレスを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

このメソッドは、画像取り込みに必要なすべての情報を収集するためにアプリケーションが使用するダイアログボックスをユーザーに表示します。たとえば、このダイアログボックスにより、ユーザーはカメラからダウンロードする画像を選択できます。スキャナーを使用する場合は、明るさやコントラストなどの画像スキャンのプロパティを指定するためにも使用されます。

このメソッドから制御が戻った後、アプリケーションは IWiaDataTransfer インターフェイスを使用して画像を取得できます。

アプリケーションは、ppIWiaItem パラメーターを通じて受け取ったインターフェイスポインターの配列の各要素に対して IUnknown::Release メソッドを呼び出す必要があります。また、CoTaskMemFree を使用してその配列を解放する必要もあります。

アプリケーションでは、デバイスと画像の選択を ファイル メニューの スキャナーまたはカメラから という名前のメニュー項目から利用できるようにすることが推奨されます。

vtbl 11 HRESULT DeviceCommand(INT lFlags, GUID* pCmdGUID, IWiaItem** pIWiaItem)

IWiaItem::DeviceCommand は、Windows Image Acquisition (WIA) ハードウェアデバイスにコマンドを発行します。

lFlags	INT	in	現在使用されていません。ゼロを設定してください。
pCmdGUID	GUID*	in	WIA ハードウェアデバイスに送信するコマンドを指定する一意の識別子を指定します。有効なデバイスコマンドの一覧については、WIA Device Commands を参照してください。
pIWiaItem	IWiaItem**	inout	出力時、このポインターは、コマンドによって作成されたアイテム (ある場合) を指します。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

アプリケーションは、このメソッドを使用してハードウェアデバイスに WIA コマンドを送信します。

アプリケーションが IWiaItem::DeviceCommand でデバイスに WIA_CMD_TAKE_PICTURE コマンドを送信すると、WIA ランタイムシステムは画像を表す IWiaItem オブジェクトを作成します。IWiaItem::DeviceCommand メソッドは、そのインターフェイスのアドレスを pIWiaItem パラメーターに格納します。

アプリケーションは、pIWiaItem パラメーターを通じて受け取ったインターフェイスポインターに対して IUnknown::Release メソッドを呼び出す必要があります。

vtbl 12 HRESULT GetRootItem(IWiaItem** ppIWiaItem)

IWiaItem::GetRootItem メソッドは、Windows Image Acquisition (WIA) ハードウェアデバイスを表すために使用されるアイテムオブジェクトのツリーのルートアイテムを取得します。

ppIWiaItem

IWiaItem**

out

ルートアイテムの IWiaItem インターフェイスへのポインターを保持する IWiaItem インターフェイスへのポインターのアドレスを受け取ります。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

WIA ハードウェアデバイスのオブジェクトツリー内の任意の IWiaItem オブジェクトから、この関数を呼び出すことでアプリケーションはルートアイテムへのポインターを取得します。

vtbl 13 HRESULT EnumDeviceCapabilities(INT lFlags, IEnumWIA_DEV_CAPS** ppIEnumWIA_DEV_CAPS)

IWiaItem::EnumDeviceCapabilities メソッドは、Windows Image Acquisition (WIA) デバイスがサポートするコマンドとイベントを調べるために使用する列挙子を作成します。

lFlags

INT

列挙する機能の種類を選択するフラグを指定します。次の値の 1 つ以上を設定できます。

フラグ	意味
WIA_DEVICE_COMMANDS	デバイスコマンドを列挙します。
WIA_DEVICE_EVENTS	デバイスイベントを列挙します。

ppIEnumWIA_DEV_CAPS

IEnumWIA_DEV_CAPS**

out

IWiaItem::EnumDeviceCapabilities が作成する IEnumWIA_DEV_CAPS インターフェイスへのポインターです。

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

WIA デバイスがサポートするコマンドとイベントの集合を取得するための列挙子オブジェクトを作成するには、このメソッドを使用します。lFlags パラメーターを使用して、どの種類のデバイス機能を列挙するかを指定できます。IWiaItem::EnumDeviceCapabilities メソッドは、列挙子オブジェクトのインターフェイスのアドレスを ppIEnumWIA_DEV_CAPS パラメーターに格納します。

アプリケーションは、ppIEnumWIA_DEV_CAPS パラメーターを通じて受け取ったインターフェイスポインターに対して IUnknown::Release メソッドを呼び出す必要があります。

vtbl 14 HRESULT DumpItemData(LPWSTR* bstrData)

このメソッドはサポートされていません。(IWiaItem.DumpItemData)

bstrData

LPWSTR*

out

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 15 HRESULT DumpDrvItemData(LPWSTR* bstrData)

このメソッドはサポートされていません。(IWiaItem.DumpDrvItemData)

bstrData

LPWSTR*

out

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 16 HRESULT DumpTreeItemData(LPWSTR* bstrData)

このメソッドはサポートされていません。(IWiaItem.DumpTreeItemData)

bstrData

LPWSTR*

out

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

vtbl 17 HRESULT Diagnostic(DWORD ulSize, BYTE* pBuffer)

このメソッドはサポートされていません。(IWiaItem.Diagnostic)

ulSize	DWORD	in
pBuffer	BYTE*	in

戻り値

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IWiaItem "{4DB1AD10-3391-11D2-9A33-00C04FA36145}"
#usecom global IWiaItem IID_IWiaItem "{}"
#comfunc global IWiaItem_GetItemType             3 var
#comfunc global IWiaItem_AnalyzeItem             4 int
#comfunc global IWiaItem_EnumChildItems          5 sptr
#comfunc global IWiaItem_DeleteItem              6 int
#comfunc global IWiaItem_CreateChildItem         7 int,wstr,wstr,sptr
#comfunc global IWiaItem_EnumRegisterEventInfo   8 int,var,sptr
#comfunc global IWiaItem_FindItemByName          9 int,wstr,sptr
#comfunc global IWiaItem_DeviceDlg               10 sptr,int,int,var,sptr
#comfunc global IWiaItem_DeviceCommand           11 int,var,sptr
#comfunc global IWiaItem_GetRootItem             12 sptr
#comfunc global IWiaItem_EnumDeviceCapabilities  13 int,sptr
#comfunc global IWiaItem_DumpItemData            14 var
#comfunc global IWiaItem_DumpDrvItemData         15 var
#comfunc global IWiaItem_DumpTreeItemData        16 var
#comfunc global IWiaItem_Diagnostic              17 int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IWiaItem "{4DB1AD10-3391-11D2-9A33-00C04FA36145}"
#usecom global IWiaItem IID_IWiaItem "{}"
#comfunc global IWiaItem_GetItemType             3 sptr
#comfunc global IWiaItem_AnalyzeItem             4 int
#comfunc global IWiaItem_EnumChildItems          5 sptr
#comfunc global IWiaItem_DeleteItem              6 int
#comfunc global IWiaItem_CreateChildItem         7 int,wstr,wstr,sptr
#comfunc global IWiaItem_EnumRegisterEventInfo   8 int,sptr,sptr
#comfunc global IWiaItem_FindItemByName          9 int,wstr,sptr
#comfunc global IWiaItem_DeviceDlg               10 sptr,int,int,sptr,sptr
#comfunc global IWiaItem_DeviceCommand           11 int,sptr,sptr
#comfunc global IWiaItem_GetRootItem             12 sptr
#comfunc global IWiaItem_EnumDeviceCapabilities  13 int,sptr
#comfunc global IWiaItem_DumpItemData            14 sptr
#comfunc global IWiaItem_DumpDrvItemData         15 sptr
#comfunc global IWiaItem_DumpTreeItemData        16 sptr
#comfunc global IWiaItem_Diagnostic              17 int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。