ホーム › UI.Shell › ITransferDestination

ITransferDestination

COM

IID48addd32-3ca5-4124-abe3-b5a72531b207継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

コピーまたは移動操作の宛先となる Shell アイテムを作成するメソッドを公開します。このインターフェイスは、ITransferDestination::Advise メソッドを提供することで、ファイル操作をより細かく制御できるようにするために用意されています。

メソッド 3

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

vtbl 3 HRESULT Advise(ITransferAdviseSink* psink, DWORD* pdwCookie)

ファイル操作の状態に関する通知を受け取るためのアドバイザリ接続を設定します。(ITransferDestination.Advise)

psink	ITransferAdviseSink*	in	このインターフェイス上のメソッドを使用して呼び出し元アプリケーションを更新するための、ITransferAdviseSink 通知インターフェイスへのポインター。
pdwCookie	DWORD*	out	この接続を一意に識別するトークンが返されるポインター。呼び出し元アプリケーションは、後でこのトークンを ITransferDestination::Unadvise メソッドに渡すことで接続を削除します。接続の確立に成功しなかった場合、この値は 0 になります。

戻り値

型: HRESULT

記載されている以外の HRESULT はすべて失敗を示します。

戻り値	説明
S_OK	インターフェイスの関連付けに成功しました。
E_UNEXPECTED	ハンドラーは 1 つのシンクインターフェイスのみを処理できます。

解説(Remarks)

発生する可能性のあるエラーをハンドラーがコールバックできるよう、他の ITransferDestination メソッドを呼び出す前に ITransferDestination::Advise を呼び出してください。設定されていない場合、ハンドラーはフィードバックが利用できないことを示すものとして扱い、"既定" の操作を実行する必要があります。

vtbl 4 HRESULT Unadvise(DWORD dwCookie)

アドバイザリ接続を終了します。(ITransferDestination.Unadvise)

dwCookie

DWORD

以前 ITransferDestination::Advise から返された接続トークン。終了する接続を識別します。

戻り値

型: HRESULT

ここに記載されている以外の HRESULT はすべて失敗を示します。

戻り値	説明
S_OK	接続が正常に終了しました。
CONNECT_E_NOCONNECTION	dwCookie の値が有効な接続を表していません。

解説(Remarks)

ITransferDestination::Advise メソッドを通じて以前に確立されたアドバイザリ接続を終了します。

vtbl 5 HRESULT CreateItem(LPWSTR pszName, DWORD dwAttributes, ULONGLONG ullSize, DWORD flags, GUID* riidItem, void** ppvItem, GUID* riidResources, void** ppvResources)

指定されたファイルを作成します。

pszName	LPWSTR	in	現在のディレクトリを基準としたファイル名を含む、null 終端バッファーへのポインター。
dwAttributes	DWORD	in	BY_HANDLE_FILE_INFORMATION 構造体で定義されている FILE_ATTRIBUTE フラグの 1 つ以上。最も重要な値は FILE_ATTRIBUTE_DIRECTORY であり、フォルダーを作成する必要があることを示します。
ullSize	ULONGLONG	in	作成するファイルのサイズ(バイト単位)。サイズが不明な場合、この値は 0 にできます。
flags	DWORD	in	ファイル操作を制御するフラグ。TRANSFER_SOURCE_FLAGS フラグの 1 つ以上。
riidItem	GUID*	in	ppvItem を通じて取得するインターフェイスの IID への参照。通常は IID_IShellItem、またはそこから派生した別のインターフェイスです。
ppvItem	void**	out	このメソッドが戻ると、riidItem で要求されたインターフェイスポインターが格納されます。通常は IShellItem またはその派生インターフェイスです。
riidResources	GUID*	in	ppvResources を通じて取得するインターフェイスの IID への参照。通常は IID_IShellItemResources、またはそこから派生した別のインターフェイスです。
ppvResources	void**	out	このメソッドが戻ると、riidResources で要求されたインターフェイスポインターが格納されます。通常は IShellItemResources またはその派生インターフェイスです。

戻り値

型: HRESULT

成功した場合は成功コードを返し、それ以外の場合はエラー値を返します。成功コードには次のものが含まれます:

S_OK: 移動に成功し、ppvItem と ppvResources の両方が有効なオブジェクトを指しています。
COPYENGINE_S_USER_IGNORED: 宛先アイテムは既に存在し、上書きされませんでした。ppvItem と ppvResources が指す値は NULL です。呼び出し元がコピーと削除操作として移動を実装している場合、呼び出し元はソースアイテムを削除して移動を完了する必要があります。

解説(Remarks)

このメソッドは、コピーまたは移動操作の宛先フォルダーを表す Shell アイテムオブジェクトを作成するために使用できます。ITransferSource インターフェイスは、IShellItem のオブジェクトを実際に宛先へ移動するメソッドを提供します。

発生する可能性のあるエラーをハンドラーがコールバックできるよう、他の ITransferDestination メソッドを呼び出す前に ITransferDestination::Advise を呼び出してください。設定されていない場合、ハンドラーはフィードバックが利用できないことを示すものとして扱い、"既定" の操作を実行する必要があります。

riidResources と ppvResources のパラメーターをまとめるには、Objbase.h で定義されている IID_PPV_ARGS マクロを使用することをお勧めします。このマクロは ppvResources の値が指すインターフェイスに基づいて正しい IID を提供するため、コーディングエラーの可能性を排除できます。

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