ホーム › Devices.ImageAcquisition › IWiaDataTransfer

IWiaDataTransfer

COM

IIDa6cef998-a5b0-11d2-a08f-00c04f72dc3c継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IWiaDataTransfer インターフェイスは、高性能なデータ転送インターフェイスです。

解説(Remarks)

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

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

メソッド 5

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

vtbl 3 HRESULT idtGetData(STGMEDIUM* pMedium, IWiaDataCallback* pIWiaDataCallback)

IWiaDataTransfer::idtGetData メソッドは、Windows Image Acquisition (WIA) デバイスから完全なファイルを取得します。

pMedium	STGMEDIUM*	inout	STGMEDIUM 構造体へのポインターです。
pIWiaDataCallback	IWiaDataCallback*	in	IWiaDataCallback インターフェイスへのポインターです。

戻り値

型: HRESULT

このメソッドは、次のいずれかの値を返すことがあります。

戻り値	説明
E_INVALIDARG	このメソッドの 1 つ以上のパラメーターに無効なデータが含まれています。
E_OUTOFMEMORY	このメソッドは、処理を完了するのに十分なメモリを割り当てることができません。
E_UNEXPECTED	不明なエラーが発生しました。
S_FALSE	アプリケーションが処理をキャンセルしました。
S_OK	画像が正常に取り込まれました。
STG_E_MEDIUMFULL	アプリケーションが画像の取り込みに使用している記憶媒体がいっぱいです。
WIA_S_NO_DEVICE_AVAILABLE	ユーザーのコンピューターに WIA ハードウェアデバイスが接続されていません。

上記の表に記載された以外の理由で失敗した場合、このメソッドはエラーコードに規定された値、または標準の COM エラーを返します。

解説(Remarks)

このメソッドはほとんどの点で IDataObject::GetData メソッドと同様に動作します。主な違いは、IWiaDataTransfer::idtGetData が IWiaDataCallback インターフェイスへのポインターを渡すための追加のパラメーターを備えている点です。アプリケーションはこの省略可能なパラメーターを使用して、データ転送中の状態通知を受け取ります。状態通知が不要な場合は、ゼロを設定してください。

データ転送の形式は、アイテムの WIA_IPA_FORMAT プロパティおよび WIA_IPA_TYMED プロパティの値によって決まります。アプリケーションは、IWiaPropertyStorage::WriteMultiple メソッドを呼び出してこれらのプロパティを設定します。

IWiaDataTransfer::idtGetBandedData メソッドとは異なり、IWiaDataTransfer::idtGetData はデータの単一のバンドではなく、WIA デバイスからアプリケーションへ完全なファイルを転送します。pMedium パラメーターは、データ転送に使用する記憶媒体の情報を格納した STGMEDIUM 構造体へのポインターです。プログラムは pIWiaDataCallback パラメーターを使用して、IWiaDataCallback インターフェイスへのポインターをこのメソッドに渡します。このメソッドは定期的にそのインターフェイスポインターを使用して BandedDataCallback メソッドを呼び出し、進行中のデータ転送に関する状態情報をアプリケーションに提供します。

pMedium 構造体の lpszFileName メンバーに NULL を渡すと、新しいファイルの名前と場所を WIA が決定します。復帰時には、pMedium 構造体の lpszFileName メンバーに新しいファイルの場所と名前が格納されます。

このメソッドが返す値が COM の成功値である場合、または転送が複数ページのファイル転送であり、返されたエラーコードが WIA_ERROR_PAPER_JAM、WIA_ERROR_PAPER_EMPTY、WIA_ERROR_PAPER_PROBLEM のいずれかである場合、WIA はファイルを削除しません。

vtbl 4 HRESULT idtGetBandedData(WIA_DATA_TRANSFER_INFO* pWiaDataTransInfo, IWiaDataCallback* pIWiaDataCallback)

IWiaDataTransfer::idtGetBandedData メソッドは、ハードウェアデバイスからアプリケーションへデータのバンドを転送します。効率化のため、アプリケーションは Windows Image Acquisition (WIA) ハードウェアデバイスから連続したバンド単位でデータを取得します。

pWiaDataTransInfo	WIA_DATA_TRANSFER_INFO*	inout	WIA_DATA_TRANSFER_INFO 構造体へのポインターです。
pIWiaDataCallback	IWiaDataCallback*	in	IWiaDataCallback インターフェイスへのポインターです。このメソッドは定期的に BandedDataCallback メソッドを呼び出し、データ転送の状態通知をアプリケーションに提供します。

戻り値

型: HRESULT

このメソッドは、次のいずれかの値を返すことがあります。

戻り値	説明
E_INVALIDARG	このメソッドの 1 つ以上のパラメーターに無効なデータが含まれています。
E_OUTOFMEMORY	このメソッドは、処理を完了するのに十分なメモリを割り当てることができません。
E_UNEXPECTED	不明なエラーが発生しました。
S_FALSE	アプリケーションが処理をキャンセルしました。
S_OK	画像が正常に取り込まれました。
STG_E_MEDIUMFULL	アプリケーションが画像の取り込みに使用している記憶媒体がいっぱいです。
WIA_S_NO_DEVICE_AVAILABLE	ユーザーのコンピューターに WIA ハードウェアデバイスが接続されていません。

上記の表に記載された以外の理由で失敗した場合、このメソッドはエラーコードに規定された値、または標準の COM エラーを返します。

解説(Remarks)

IWiaDataTransfer::idtGetBandedData メソッドは、Component Object Model / リモートプロシージャコール (COM/RPC) のマーシャリング層を介した余分なデータコピーを行わずにデータを転送するために、メモリセクションを割り当てます。このメモリセクションは、アプリケーションとハードウェアデバイスのアイテムツリーとの間で共有されます。

必要に応じて、アプリケーションは IWiaDataTransfer::idtGetBandedData が共有セクションとして使用するメモリブロックへのポインターを渡すこともできます。アプリケーションは、IWiaDataTransfer::idtGetBandedData を呼び出す前に、そのポインターを WIA_DATA_TRANSFER_INFO 構造体の ulSection メンバーに格納することでこのハンドルを渡します。

アプリケーションはダブルバッファリングを使用することでパフォーマンスを向上できます。そのためには、WIA_DATA_TRANSFER_INFO 構造体の bDoubleBuffer メンバーを TRUE に設定する必要があります。IWiaDataTransfer::idtGetBandedData メソッドはデータバッファーを半分に分割します。バッファーの一方の半分がいっぱいになると、IWiaDataTransfer::idtGetBandedData は pIWiaDataCallback パラメーターで渡された IWiaDataCallback ポインターを使用してアプリケーションに通知を送ります。アプリケーションがいっぱいになった半分からデータを取得している間、デバイスドライバーはもう一方の半分にデータを書き込むことができます。

vtbl 5 HRESULT idtQueryGetData(WIA_FORMAT_INFO* pfe)

IWiaDataTransfer::idtQueryGetData メソッドは、Windows Image Acquisition (WIA) デバイスに問い合わせて、そのデバイスがサポートするデータ形式の種類を判別するためにアプリケーションが使用します。

pfe

WIA_FORMAT_INFO*

inoptional

WIA_FORMAT_INFO 構造体へのポインターです。

戻り値

型: HRESULT

このメソッドが成功すると S_OK を返します。それ以外の場合は、エラーコードに規定された値、または標準の COM エラーを返します。

解説(Remarks)

このメソッドは、デバイスがサポートするデータ形式を判別するためにデバイスへ問い合わせます。データ転送の前に、アプリケーションは使用予定の媒体とデータ形式の情報を WIA_FORMAT_INFO 構造体に設定できます。続いて IWiaDataTransfer::idtQueryGetData を呼び出し、そのデータ形式とメディアの種類がデバイスでサポートされていれば戻り値として S_OK を受け取ります。

vtbl 6 HRESULT idtEnumWIA_FORMAT_INFO(IEnumWIA_FORMAT_INFO** ppEnum)

IWiaDataTransfer::idtEnumWIA_FORMAT_INFO メソッドは、IEnumWIA_FORMAT_INFO インターフェイスのバンド転送用の実装を作成します。

ppEnum

IEnumWIA_FORMAT_INFO**

out

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

戻り値

型: HRESULT

次の表に記載された以外の理由で失敗した場合、このメソッドは標準の COM エラーを返します。

戻り値	説明
E_INVALIDARG	ppEnum パラメーターが IEnumWIA_FORMAT_INFO インターフェイスへのポインターのアドレスではありません。
E_OUTOFMEMORY	列挙子オブジェクトを作成するのに十分なメモリがありません。
S_OK	列挙子オブジェクトが正常に作成されました。

解説(Remarks)

このメソッドは、WIA_FORMAT_INFO 構造体の配列を列挙するためにアプリケーションが使用する IEnumWIA_FORMAT_INFO インターフェイスを作成します。これにより、アプリケーションはバンドデータの転送時に、受信するデータの形式とメディアの種類を判別できます。

アプリケーションは、ppEnum パラメーターを通じて受け取ったインターフェイスポインターに対して IUnknown::Release メソッドを呼び出す必要があることに注意してください。

vtbl 7 HRESULT idtGetExtendedTransferInfo(WIA_EXTENDED_TRANSFER_INFO* pExtendedTransferInfo)

IWiaDataTransfer::idtGetExtendedTransferInfo は、バンドデータ転送の場合に、データ転送バッファーに関する拡張情報を取得します。

pExtendedTransferInfo

WIA_EXTENDED_TRANSFER_INFO*

out

拡張情報を格納する WIA_EXTENDED_TRANSFER_INFO 構造体へのポインターです。

戻り値

型: 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_IWiaDataTransfer "{A6CEF998-A5B0-11D2-A08F-00C04F72DC3C}"
#usecom global IWiaDataTransfer IID_IWiaDataTransfer "{}"
#comfunc global IWiaDataTransfer_idtGetData                  3 var,sptr
#comfunc global IWiaDataTransfer_idtGetBandedData            4 var,sptr
#comfunc global IWiaDataTransfer_idtQueryGetData             5 var
#comfunc global IWiaDataTransfer_idtEnumWIA_FORMAT_INFO      6 sptr
#comfunc global IWiaDataTransfer_idtGetExtendedTransferInfo  7 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IWiaDataTransfer "{A6CEF998-A5B0-11D2-A08F-00C04F72DC3C}"
#usecom global IWiaDataTransfer IID_IWiaDataTransfer "{}"
#comfunc global IWiaDataTransfer_idtGetData                  3 sptr,sptr
#comfunc global IWiaDataTransfer_idtGetBandedData            4 sptr,sptr
#comfunc global IWiaDataTransfer_idtQueryGetData             5 sptr
#comfunc global IWiaDataTransfer_idtEnumWIA_FORMAT_INFO      6 sptr
#comfunc global IWiaDataTransfer_idtGetExtendedTransferInfo  7 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。