ITransferSource

COM

IID00adb003-bde9-45c6-8e29-d09f9353e108継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IShellItem に対するコピー、移動、ごみ箱への移動などの操作を行うメソッドを公開します。このインターフェイスは ITransferSource::Advise メソッドを提供することで、ファイル操作をより細かく制御できるようにします。

メソッド 13

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

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

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

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

戻り値

型: HRESULT

ここに挙げたもの以外の HRESULT は失敗を示します。

戻り値	説明
S_OK	インターフェイスが正常に関連付けられました。
E_UNEXPECTED	ハンドラーは 1 つのシンクインターフェイスしか処理できません。

解説(Remarks)

アドバイザリセッションを有効にするには、このインターフェイスの他のメソッドを呼び出す前に ITransferSource::Advise を呼び出してください。設定されていない場合、ハンドラーはフィードバックが利用できないことを示すものとみなし、呼び出し元のアプリケーションに問い合わせることなく「既定の」操作を行うべきです。

vtbl 4 HRESULT Unadvise(DWORD dwCookie)

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

dwCookie

DWORD

ITransferSource::Advise メソッドから以前に返された接続トークン。

戻り値

型: HRESULT

ここに挙げたもの以外の HRESULT は失敗を示します。

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

解説(Remarks)

ITransferSource::Advise メソッドを通じて以前に確立されたアドバイザリ接続を終了します。dwCookie パラメーターは、終了する接続を識別します。

vtbl 5 HRESULT SetProperties(IPropertyChangeArray* pproparray)

アイテムに適用するプロパティを設定します。

pproparray

IPropertyChangeArray*

プロパティと変更後の値の配列。

戻り値

型: HRESULT

S_OK 以外の戻り値はすべて失敗を示します。

vtbl 6 HRESULT OpenItem(IShellItem* psi, DWORD flags, GUID* riid, void** ppv)

アイテムをコピー用に開きます。リソースを列挙できるオブジェクト (IShellItemResources) を返します。

psi	IShellItem*	in	開く IShellItem へのポインター。
flags	DWORD	in	ファイル操作を制御するフラグ。TRANSFER_SOURCE_FLAGS 定数の 1 つ以上。
riid	GUID*	in	ppv に返すインターフェイスの IID (インターフェイス ID または GUID) への参照。これは IShellItemResources、または IShellItemResources から派生したインターフェイスである必要があります。
ppv	void**	out	このメソッドが返るとき、riid で指定されたインターフェイスへのポインターのアドレスが格納されます。

戻り値

型: HRESULT

成功した場合は S_OK を返します。それ以外の場合は、以下の特定の Shell コードのいずれか、またはシステムエラーコードを返します。

戻り値	説明
COPYENGINE_S_YES	ユーザーがダイアログで「はい」と応答しました。
COPYENGINE_S_USER_RETRY	ユーザーが現在の操作の再試行を選択しました。
COPYENGINE_S_USER_IGNORED	ユーザーがダイアログで「いいえ」と応答しました。
COPYENGINE_S_MERGE	ユーザーがフォルダーのマージを選択しました。
COPYENGINE_S_USER_RETRY_WITH_NEW_NAME	ユーザーが新しい名前でファイルを再試行することを選択しました。
COPYENGINE_S_DONT_PROCESS_CHILDREN	子アイテムは処理すべきではありません。
COPYENGINE_S_PENDING	エラーはキューに入れられ、後で表示されます。
COPYENGINE_E_USER_CANCELLED	ユーザーが現在の操作をキャンセルしました。
COPYENGINE_E_REQUIRES_ELEVATION	操作には昇格された権限が必要です。

vtbl 7 HRESULT MoveItem(IShellItem* psi, IShellItem* psiParentDst, LPWSTR pszNameDst, DWORD flags, IShellItem** ppsiNew)

ボリューム/名前空間内でアイテムを移動し、新しい場所の IShellItem を返します。

psi	IShellItem*	in	移動する IShellItem へのポインター。
psiParentDst	IShellItem*	in	移動先の新しい親アイテムを表す IShellItem へのポインター。
pszNameDst	LPWSTR	in	移動先のパスを含む null で終わるバッファーへのポインター。
flags	DWORD	in	ファイル操作を制御するフラグ。TRANSFER_SOURCE_FLAGS 定数の 1 つ以上。
ppsiNew	IShellItem**	out	このメソッドが正常に返るとき、新しい場所の IShellItem へのポインターのアドレスが格納されます。

戻り値

型: HRESULT

移動が成功した場合は S_OK を返します。その場合、ppsiNew は新しいアイテムのアドレスを指します。その他の成功コードおよび失敗コードには、以下のものがあります。

戻り値	説明
COPYENGINE_S_USER_IGNORED	移動先のアイテムが既に存在し、上書きされませんでした。この場合、ppsiNew は NULL であり、呼び出し元は移動元のアイテムを削除する必要があります。
COPYENGINE_S_MERGE	移動先のアイテムが既に存在し、ユーザーが移動元と移動先のフォルダーをマージすることを選択しました。この場合、ppsiNew は NULL 値を指し、呼び出し元は移動元のアイテムを削除する必要があります。
E_NOINTERFACE	移動対象のアイテムがフォルダーの場合、呼び出し元は移動操作をコピーおよび削除操作に変換する必要があります。
ERROR_NOT_SAME_DEVICE	呼び出し元は移動操作をコピーおよび削除操作に変換する必要があります。このエラーは `HRESULT_FROM_WIN32(ERROR_NOT_SAME_DEVICE)` として現れます。
ERROR_FILE_EXISTS	フォルダーを移動する際、呼び出し元は移動操作をコピーおよび削除操作に変換する必要があります。移動先のアイテムは ITransferDestination をサポートしている必要があります。このエラーは `HRESULT_FROM_WIN32(ERROR_FILE_EXISTS)` として現れます。
ERROR_ALREADY_EXISTS	フォルダーを移動する際、呼び出し元は移動操作をコピーおよび削除操作に変換する必要があります。移動先のアイテムは ITransferDestination をサポートしている必要があります。このエラーは `HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS)` として現れます。

vtbl 8 HRESULT RecycleItem(IShellItem* psiSource, IShellItem* psiParentDest, DWORD flags, IShellItem** ppsiNewDest)

指定されたごみ箱の場所にアイテムを移動し、新しい場所のアイテムを返します。

psiSource	IShellItem*	in	ごみ箱に移動する IShellItem へのポインター。
psiParentDest	IShellItem*	in	ごみ箱の場所 (アイテムの新しい親) の IShellItem へのポインター。
flags	DWORD	in	ファイル操作を制御するフラグ。TRANSFER_SOURCE_FLAGS 定数の 1 つ以上。
ppsiNewDest	IShellItem**	out	このメソッドが返るとき、ごみ箱に移動された IShellItem へのポインターのアドレスが格納されます。

戻り値

型: HRESULT

以下のいずれか、またはエラーコードを返します。

戻り値	説明
COPYENGINE_S_YES	ユーザーがダイアログで「はい」と応答しました。
COPYENGINE_S_USER_RETRY	ユーザーが現在の操作の再試行を選択しました。
COPYENGINE_S_USER_IGNORED	ユーザーがダイアログで「いいえ」と応答しました。
COPYENGINE_S_DONT_PROCESS_CHILDREN	子アイテムは処理すべきではありません。
COPYENGINE_S_PENDING	エラーはキューに入れられ、後で表示されます。
COPYENGINE_E_USER_CANCELLED	ユーザーが現在の操作をキャンセルしました。
COPYENGINE_E_REQUIRES_ELEVATION	操作には昇格された権限が必要です。

vtbl 9 HRESULT RemoveItem(IShellItem* psiSource, DWORD flags)

アイテムをごみ箱に移動せずに削除します。

psiSource	IShellItem*	in	削除する IShellItem へのポインター。
flags	DWORD	in	ファイル操作を制御するフラグ。TRANSFER_SOURCE_FLAGS 定数の 1 つ以上。

戻り値

型: HRESULT

以下のいずれか、またはエラーコードを返します。

戻り値	説明
COPYENGINE_S_YES	ユーザーがダイアログで「はい」と応答しました
COPYENGINE_S_USER_RETRY	ユーザーが現在の操作の再試行を選択しました
COPYENGINE_S_USER_IGNORED	ユーザーがダイアログで「いいえ」と応答しました。
COPYENGINE_S_MERGE	ユーザーがフォルダーのマージを選択しました。
COPYENGINE_S_USER_RETRY_WITH_NEW_NAME	ユーザーが新しい名前でファイルを再試行することを選択しました。
COPYENGINE_S_DONT_PROCESS_CHILDREN	子アイテムは処理すべきではありません。
COPYENGINE_S_PENDING	エラーはキューに入れられ、後で表示されます。
COPYENGINE_E_USER_CANCELLED	ユーザーが現在の操作をキャンセルしました。
COPYENGINE_E_REQUIRES_ELEVATION	操作には昇格された権限が必要です。

vtbl 10 HRESULT RenameItem(IShellItem* psiSource, LPWSTR pszNewName, DWORD flags, IShellItem** ppsiNewDest)

アイテムの名前を変更し、新しい名前を持つ IShellItem を返します。

psiSource	IShellItem*	in	名前を変更する IShellItem オブジェクトへのポインター。
pszNewName	LPWSTR	in	新しい名前を含む null で終わる Unicode 文字列へのポインター。
flags	DWORD	in	ファイル操作を制御するフラグ。TRANSFER_SOURCE_FLAGS 定数の 1 つ以上。
ppsiNewDest	IShellItem**	out	このメソッドが返るとき、IShellItem オブジェクトへのポインターのアドレスが格納されます。

戻り値

型: HRESULT

以下のいずれか、またはエラーコードを返します。

戻り値	説明
COPYENGINE_S_YES	ユーザーがダイアログで「はい」と応答しました。
COPYENGINE_S_USER_RETRY	ユーザーが現在の操作の再試行を選択しました。
COPYENGINE_S_USER_IGNORED	ユーザーがダイアログで「いいえ」と応答しました。
COPYENGINE_S_MERGE	ユーザーがフォルダーのマージを選択しました。
COPYENGINE_S_USER_RETRY_WITH_NEW_NAME	ユーザーが新しい名前でファイルを再試行することを選択しました。
COPYENGINE_S_DONT_PROCESS_CHILDREN	子アイテムは処理すべきではありません。
COPYENGINE_S_PENDING	エラーはキューに入れられ、後で表示されます。
COPYENGINE_E_USER_CANCELLED	ユーザーが現在の操作をキャンセルしました。
COPYENGINE_E_REQUIRES_ELEVATION	操作には昇格された権限が必要です。

vtbl 11 HRESULT LinkItem(IShellItem* psiSource, IShellItem* psiParentDest, LPWSTR pszNewName, DWORD flags, IShellItem** ppsiNewDest)

実装されていません。(ITransferSource.LinkItem)

psiSource	IShellItem*	in	移動元のアイテムを表す IShellItem へのポインター。
psiParentDest	IShellItem*	in	リンクの親となる IShellItem へのポインター。
pszNewName	LPWSTR	inoptional	リンクの名前を含む null で終わる Unicode 文字列へのポインター。
flags	DWORD	in	ファイル操作を制御するフラグ。値は TRANSFER_SOURCE_FLAGS 定数の 1 つ以上です。
ppsiNewDest	IShellItem**	out	このメソッドが返るとき、リンクの IShellItem へのポインターのアドレスが格納されます。

戻り値

型: HRESULT

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

vtbl 12 HRESULT ApplyPropertiesToItem(IShellItem* psiSource, IShellItem** ppsiNew)

一連のプロパティ変更をアイテムに適用します。

psiSource	IShellItem*	in	変更する IShellItem へのポインター。
ppsiNew	IShellItem**	out	このメソッドが返るとき、変更された IShellItem へのポインターのアドレスが格納されます。

戻り値

型: HRESULT

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

vtbl 13 HRESULT GetDefaultDestinationName(IShellItem* psiSource, IShellItem* psiParentDest, LPWSTR* ppszDestinationName)

Shell アイテムの既定の名前を取得します。

psiSource	IShellItem*	in	IShellItem へのポインター。
psiParentDest	IShellItem*	in	ファイル操作の対象となる移動先の親 IShellItem へのポインター。
ppszDestinationName	LPWSTR*	out	このメソッドが返るとき、既定の名前を含む null で終わる Unicode 文字列へのポインターが格納されます。

戻り値

型: HRESULT

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

解説(Remarks)

Shell アイテムの既定の名前を取得します (アイテムの解析名と異なる場合)。

vtbl 14 HRESULT EnterFolder(IShellItem* psiChildFolderDest)

フォルダーがファイル操作の移動先であることを通知します。

psiChildFolderDest

IShellItem*

移動先フォルダーの IShellItem へのポインター。

戻り値

型: HRESULT

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

解説(Remarks)

このメソッドは、再帰的な操作でフォルダーまたはサブフォルダーの処理を開始するときに呼び出されます。たとえば、移動元フォルダーを移動先フォルダーにコピーする場合、psiChildFolderDest に移動先フォルダーを設定して ITransferSource::EnterFolder メソッドを呼び出す必要があります。

vtbl 15 HRESULT LeaveFolder(IShellItem* psiChildFolderDest)

フォルダーがファイル操作の移動先ではなくなったことを通知します。

psiChildFolderDest

IShellItem*

移動先フォルダーの IShellItem へのポインター。

戻り値

型: HRESULT

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

解説(Remarks)

このメソッドは、移動先フォルダーに対する再帰的なファイル操作の最後に呼び出されます。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ITransferSource "{00ADB003-BDE9-45C6-8E29-D09F9353E108}"
#usecom global ITransferSource IID_ITransferSource "{}"
#comfunc global ITransferSource_Advise                     3 sptr,var
#comfunc global ITransferSource_Unadvise                   4 int
#comfunc global ITransferSource_SetProperties              5 sptr
#comfunc global ITransferSource_OpenItem                   6 sptr,int,var,sptr
#comfunc global ITransferSource_MoveItem                   7 sptr,sptr,wstr,int,sptr
#comfunc global ITransferSource_RecycleItem                8 sptr,sptr,int,sptr
#comfunc global ITransferSource_RemoveItem                 9 sptr,int
#comfunc global ITransferSource_RenameItem                 10 sptr,wstr,int,sptr
#comfunc global ITransferSource_LinkItem                   11 sptr,sptr,wstr,int,sptr
#comfunc global ITransferSource_ApplyPropertiesToItem      12 sptr,sptr
#comfunc global ITransferSource_GetDefaultDestinationName  13 sptr,sptr,var
#comfunc global ITransferSource_EnterFolder                14 sptr
#comfunc global ITransferSource_LeaveFolder                15 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_ITransferSource "{00ADB003-BDE9-45C6-8E29-D09F9353E108}"
#usecom global ITransferSource IID_ITransferSource "{}"
#comfunc global ITransferSource_Advise                     3 sptr,sptr
#comfunc global ITransferSource_Unadvise                   4 int
#comfunc global ITransferSource_SetProperties              5 sptr
#comfunc global ITransferSource_OpenItem                   6 sptr,int,sptr,sptr
#comfunc global ITransferSource_MoveItem                   7 sptr,sptr,wstr,int,sptr
#comfunc global ITransferSource_RecycleItem                8 sptr,sptr,int,sptr
#comfunc global ITransferSource_RemoveItem                 9 sptr,int
#comfunc global ITransferSource_RenameItem                 10 sptr,wstr,int,sptr
#comfunc global ITransferSource_LinkItem                   11 sptr,sptr,wstr,int,sptr
#comfunc global ITransferSource_ApplyPropertiesToItem      12 sptr,sptr
#comfunc global ITransferSource_GetDefaultDestinationName  13 sptr,sptr,sptr
#comfunc global ITransferSource_EnterFolder                14 sptr
#comfunc global ITransferSource_LeaveFolder                15 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。