ホーム › UI.Shell › IDataObjectAsyncCapability

IDataObjectAsyncCapability

COM

IID3d8b0590-f691-11d2-8ea9-006097df5bd4継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

通常は同期的なインターフェイスを非同期的に機能させることを可能にします。

解説(Remarks)

IDataObjectAsyncCapability は、データオブジェクトによって実装されるオプションのインターフェイスです。ドロップターゲットがドロップソースと連携して、データオブジェクトからデータを非同期的に抽出できるようにします。

このインターフェイスは主に、ドラッグアンドドロップおよびクリップボード操作で使用されるデータオブジェクトによってエクスポートされます。通常、そのような操作は同期的です。しかし、データのレンダリングに時間がかかる場合、IDataObjectAsyncCapability を使用することで、データの抽出をバックグラウンドスレッドで実行できます。このインターフェイスの使用方法の詳細については、Handling Shell Data Transfer Scenarios の Dragging and Dropping Shell Objects Asynchronously セクションを参照してください。

ドロップソースとターゲットは、時間のかかるデータ抽出処理をバックグラウンドスレッドで処理させたい場合に、このインターフェイスを使用します。

メソッド 5

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

vtbl 3 HRESULT SetAsyncMode(BOOL fDoOpAsync)

データオブジェクトが非同期のデータ抽出をサポートするかどうかを指定するために、ドロップソースによって呼び出されます。

fDoOpAsync

BOOL

非同期操作がサポートされている場合は VARIANT_TRUE、それ以外の場合は VARIANT_FALSE。既定値は VARIANT_FALSE です。

戻り値

型: HRESULT

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

解説(Remarks)

このメソッドは、データオブジェクトが非同期のデータ抽出をサポートすることを示すために、ドロップソースによって呼び出されます。後で IDataObjectAsyncCapability::GetAsyncMode が使用できるように、fDoOpAsync を保存してください。ドロップターゲットは、IDataObjectAsyncCapability::GetAsyncMode を呼び出して fDoOpAsync の値を取得することで、非同期のデータ抽出がサポートされているかどうかを判断します。

fDoOpAsync が VARIANT_TRUE に設定されている場合、SetAsyncMode は IDataObjectAsyncCapability::AddRef を呼び出し、IDataObjectAsyncCapability::EndOperation で使用するためにインターフェイスポインターを保存する必要があります。

vtbl 4 HRESULT GetAsyncMode(BOOL* pfIsOpAsync)

データオブジェクトが非同期のデータ抽出をサポートするかどうかを判断するために、ドロップターゲットによって呼び出されます。

pfIsOpAsync

BOOL*

out

非同期操作がサポートされている場合は VARIANT_TRUE、それ以外の場合は VARIANT_FALSE。

戻り値

型: HRESULT

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

解説(Remarks)

このメソッドの目的は、IDataObjectAsyncCapability::SetAsyncMode メソッドの fDoOpAsync パラメーターの値をドロップターゲットに提供することです。このパラメーターは、既定では VARIANT_FALSE に設定されています。データオブジェクトが非同期のデータ抽出をサポートする場合は、IDataObjectAsyncCapability::SetAsyncMode を呼び出し、fDoOpAsync を VARIANT_TRUE に設定する必要があります。

vtbl 5 HRESULT StartOperation(IBindCtx* pbcReserved)

非同期のデータ抽出が開始されることを示すために、ドロップターゲットによって呼び出されます。

pbcReserved

IBindCtx*

inoptional

予約済み。この値は nullptr に設定してください。

戻り値

型: HRESULT

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

解説(Remarks)

ドロップターゲットは、非同期のデータ抽出が開始されることをデータオブジェクトに通知するために、このメソッドを呼び出します。このメソッドは、IDataObjectAsyncCapability::InOperation によって返せるように、この情報を保存する必要があります。StartOperation が呼び出されると、ドロップターゲットは通常の同期的なデータ抽出の場合と同様に IDropTarget::Drop の呼び出しから復帰します。

vtbl 6 HRESULT InOperation(BOOL* pfInAsyncOp)

ターゲットがデータを非同期的に抽出しているかどうかを判断するために、ドロップソースによって呼び出されます。

pfInAsyncOp

BOOL*

out

データ抽出が非同期的に処理されている場合は VARIANT_TRUE、それ以外の場合は VARIANT_FALSE。

戻り値

型: HRESULT

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

解説(Remarks)

このメソッドは、DoDragDrop が復帰した後にドロップソースによって呼び出されます。pfInAsyncOp パラメーターは、ドロップターゲットが IDataObjectAsyncCapability::StartOperation を呼び出した場合にのみ VARIANT_TRUE に設定してください。

vtbl 7 HRESULT EndOperation(HRESULT hResult, IBindCtx* pbcReserved, DWORD dwEffects)

非同期のデータ抽出が終了したことをデータオブジェクトに通知します。

hResult	HRESULT	in	データ抽出の結果を示します。成功した場合はこの値を S_OK に、それ以外の場合は COM エラーコードに設定してください。
pbcReserved	IBindCtx*	in	予約済み。nullptr に設定してください。
dwEffects	DWORD	in	最適化された移動の結果を示す DROPEFFECT 値。これは、通常のデータ抽出操作で CFSTR_PERFORMEDDROPEFFECT 形式としてデータオブジェクトに渡される値と同じ値である必要があります。

戻り値

型: HRESULT

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

解説(Remarks)

EndOperation は、IDataObjectAsyncCapability::SetAsyncMode によって保存された IDataObjectAsyncCapability ポインターを取得し、そのパラメーター値をそのインターフェイスの IDataObjectAsyncCapability::EndOperation メソッドに渡します。次に、EndOperation は IDataObjectAsyncCapability ポインターを解放します。

EndOperation は、関連するクリーンアップ処理も担当します。処理が完了すると、EndOperation はプライベートインターフェイスを介してドロップソースに通知する必要があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IDataObjectAsyncCapability "{3D8B0590-F691-11D2-8EA9-006097DF5BD4}"
#usecom global IDataObjectAsyncCapability IID_IDataObjectAsyncCapability "{}"
#comfunc global IDataObjectAsyncCapability_SetAsyncMode    3 int
#comfunc global IDataObjectAsyncCapability_GetAsyncMode    4 var
#comfunc global IDataObjectAsyncCapability_StartOperation  5 sptr
#comfunc global IDataObjectAsyncCapability_InOperation     6 var
#comfunc global IDataObjectAsyncCapability_EndOperation    7 int,sptr,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IDataObjectAsyncCapability "{3D8B0590-F691-11D2-8EA9-006097DF5BD4}"
#usecom global IDataObjectAsyncCapability IID_IDataObjectAsyncCapability "{}"
#comfunc global IDataObjectAsyncCapability_SetAsyncMode    3 int
#comfunc global IDataObjectAsyncCapability_GetAsyncMode    4 sptr
#comfunc global IDataObjectAsyncCapability_StartOperation  5 sptr
#comfunc global IDataObjectAsyncCapability_InOperation     6 sptr
#comfunc global IDataObjectAsyncCapability_EndOperation    7 int,sptr,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。