ITransferAdviseSink
COM公式ドキュメント
状態の収集と失敗情報の取得をサポートするメソッドを公開します。
メソッド 7
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
vtbl 3 HRESULT UpdateProgress(ULONGLONG ullSizeCurrent, ULONGLONG ullSizeTotal, INT nFilesCurrent, INT nFilesTotal, INT nFoldersCurrent, INT nFoldersTotal)
UI 上の転送進行状況を更新します。
| ullSizeCurrent | ULONGLONG | in | 現在の操作で処理済みのバイト数。 |
| ullSizeTotal | ULONGLONG | in | 現在の操作における総バイト数。 |
| nFilesCurrent | INT | in | 現在の操作で処理済みのファイル数。 |
| nFilesTotal | INT | in | 操作全体のファイル総数。前回のこのメソッド呼び出しから値が変化していないことを示すには 0 を設定します。 |
| nFoldersCurrent | INT | in | 現在の操作で処理済みのフォルダー数。 |
| nFoldersTotal | INT | in | 操作全体のフォルダー総数。前回のこのメソッド呼び出しから値が変化していないことを示すには 0 を設定します。 |
戻り値
型: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
解説(Remarks)
前回のこのメソッド呼び出しから合計値が変化していないことを示すには、ullSizeTotal、nFilesTotal、nFoldersTotal をすべて 0 に設定します。
前回のこのメソッド呼び出しから進行状況が変化していないことを示すには、6 つのパラメーターすべてを 0 に設定します。
実装者への注意
この関数の実装者は、ユーザーが キャンセル ボタンをクリックした場合など、操作が完了する前に終了する必要がある場合にエラーコードを返す必要があります。転送状態を更新します。
| ts | DWORD | in | 転送状態。次のいずれかの値です。 TS_NONE (0x00000000)0x00000000。転送は実行されていません。 TS_PERFORMING (0x00000001)0x00000001。転送を実行中です。 TS_PREPARING (0x00000002)0x00000002。転送の開始準備中です。たとえば、必要な容量を計算している場合にこのフラグが設定されます。 TS_INDETERMINATE (0x00000004)0x00000004。転送の長さが不明です。 |
戻り値
型: HRESULT
このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。
vtbl 5 HRESULT ConfirmOverwrite(IShellItem* psiSource, IShellItem* psiDestParent, LPWSTR pszName)
既存の項目を上書きしてよいかどうかを確認するメッセージをユーザーに表示します。
| psiSource | IShellItem* | in | コピー元の IShellItem へのポインター。 |
| psiDestParent | IShellItem* | in | コピー先の親フォルダーを表す IShellItem へのポインター。 |
| pszName | LPWSTR | in | コピー先での項目の希望する名前を含むワイド文字列へのポインター。NULL の場合、名前は psiSource が指す Shell 項目と同じになります。 |
戻り値
型: HRESULT
以下に示す戻り値は、操作がどのように終了したかを呼び出し側プロセスに通知するために、このメソッドが特に返すものです。このメソッドの動作中にその他の結果やエラーが発生した場合は、それらを呼び出し側プロセスに返す必要があります。
| 戻りコード | 説明 |
|---|---|
| ユーザーが 無視 をクリックしました。呼び出し側プロセスは、必要に応じて他のファイルの処理を続行できます。 | |
| ユーザーが キャンセル をクリックしました。現在のドキュメントの処理を停止し、現在のプロセスを終了します。 |
vtbl 6 HRESULT ConfirmEncryptionLoss(IShellItem* psiSource)
この操作で暗号化が失われてもよいかどうかを確認するメッセージをユーザーに表示します。
| psiSource | IShellItem* | in | 暗号化情報が失われるファイルの IShellItem へのポインター。 |
戻り値
型: HRESULT
次のいずれかの Shell 固有のコード、またはシステムエラーコードを返します。
| 戻りコード | 説明 |
|---|---|
| ユーザーがダイアログで「はい」と応答しました。暗号化なしでコピーを続行します。 | |
| ユーザーがダイアログで「いいえ」と応答しました。 | |
| エラーがキューに入れられ、後で表示されます。このファイルに対する操作はスキップされます。 |
vtbl 7 HRESULT FileFailure(IShellItem* psi, LPWSTR pszItem, HRESULT hrError, LPWSTR pszRename, DWORD cchRename)
失敗が発生し、ユーザーの操作が必要な場合に呼び出されます。
| psi | IShellItem* | in | 操作が失敗した対象の IShellItem。 |
| pszItem | LPWSTR | in | 省略可能。ファイル名を含む null 終端バッファーへのポインター。この値が NULL の場合、psi パラメーターで指定された名前が使用されます。 |
| hrError | HRESULT | in | 失敗によって生成されたエラーコード。このエラーはコピーエンジンで処理する必要があります。 |
| pszRename | LPWSTR | inout | 省略可能。このメソッドが返るときに、ファイルの新しい名前を含む null 終端バッファーへのポインターが格納されます。名前の長さは cchRename を超えることはできません。このパラメーターが NULL の場合、名前を変更するオプションは提供されません。 |
| cchRename | DWORD | in | pszRename バッファーのサイズ（文字数）。 |
戻り値
型: HRESULT
その他の HRESULT は呼び出し側プロセスに返す必要があります。失敗が処理されない場合、戻り値は hrError にする必要があります。
| 戻りコード | 説明 |
|---|---|
| ユーザーが 再試行 をクリックしました。ハンドラーはファイル操作を再試行する必要があります。 | |
|
ユーザーが キャンセル をクリックしました。コピージョブ全体が終了されます。ハンドラーはこのコードをコピーエンジンに返す必要があります。 |
| ユーザーが 無視 をクリックしました。ハンドラーは項目の作成をスキップし、このコードをコピーエンジンに返す必要があります。 |
vtbl 8 HRESULT SubStreamFailure(IShellItem* psi, LPWSTR pszStreamName, HRESULT hrError)
セカンダリストリームに関わる失敗が発生し、ユーザーの操作が必要な場合に呼び出されます。
| psi | IShellItem* | in | 失敗の原因となった IShellItem へのポインター。 |
| pszStreamName | LPWSTR | in | 操作で失われるデータの名前。 |
| hrError | HRESULT | in | 生成されたエラーコード。コピーエンジンで処理する必要があります。 |
戻り値
型: HRESULT
その他の HRESULT は上位に渡す必要があります。失敗が処理されない場合、戻り値は hrError にする必要があります。
| 戻りコード | 説明 |
|---|---|
|
ハンドラーはファイル操作を再試行する必要があります。 |
|
ハンドラーは pszRename バッファーで返された名前を使用してファイル操作を再試行する必要があります。 |
|
ユーザーは、ハンドラーが既存のファイルを上書きすべきであることを指示しました。 |
|
ユーザーは、ハンドラーがセキュリティ記述子なしで操作を再試行すべきであることを指示しました。 |
|
ユーザーが キャンセル をクリックしました。コピージョブ全体が終了されます。ハンドラーはこのコードをコピーエンジンに返す必要があります。 |
vtbl 9 HRESULT PropertyFailure(IShellItem* psi, PROPERTYKEY* pkey, HRESULT hrError)
ファイルプロパティに関わる失敗が発生し、ユーザーの操作が必要な場合に呼び出されます。
| psi | IShellItem* | in | 失敗の原因となった IShellItem へのポインター。 |
| pkey | PROPERTYKEY* | in | 失われるプロパティに対応する値。NULL 値は、すべてのプロパティが失われたことを示します。 |
| hrError | HRESULT | in | 失敗によって生成されたエラーコード。コピーエンジンで処理する必要があります。 |
戻り値
型: HRESULT
その他の HRESULT は上位に渡す必要があります。失敗が処理されない場合、戻り値は hrError にする必要があります。
| 戻りコード | 説明 |
|---|---|
|
ハンドラーはファイル操作を再試行する必要があります。 |
|
ハンドラーは pszRename バッファーで返された名前を使用してファイル操作を再試行する必要があります。 |
|
ユーザーは、ハンドラーが既存のファイルを上書きすべきであることを指示しました。 |
|
ユーザーは、ハンドラーがセキュリティ記述子なしで操作を再試行すべきであることを指示しました。 |
|
ユーザーが キャンセル をクリックしました。コピージョブ全体が終了されます。ハンドラーはこのコードをコピーエンジンに返す必要があります。 |
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
出力引数:
#define global IID_ITransferAdviseSink "{D594D0D8-8DA7-457B-B3B4-CE5DBAAC0B88}" #usecom global ITransferAdviseSink IID_ITransferAdviseSink "{}" #comfunc global ITransferAdviseSink_UpdateProgress 3 int64,int64,int,int,int,int #comfunc global ITransferAdviseSink_UpdateTransferState 4 int #comfunc global ITransferAdviseSink_ConfirmOverwrite 5 sptr,sptr,wstr #comfunc global ITransferAdviseSink_ConfirmEncryptionLoss 6 sptr #comfunc global ITransferAdviseSink_FileFailure 7 sptr,wstr,int,var,int #comfunc global ITransferAdviseSink_SubStreamFailure 8 sptr,wstr,int #comfunc global ITransferAdviseSink_PropertyFailure 9 sptr,var,int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_ITransferAdviseSink "{D594D0D8-8DA7-457B-B3B4-CE5DBAAC0B88}" #usecom global ITransferAdviseSink IID_ITransferAdviseSink "{}" #comfunc global ITransferAdviseSink_UpdateProgress 3 int64,int64,int,int,int,int #comfunc global ITransferAdviseSink_UpdateTransferState 4 int #comfunc global ITransferAdviseSink_ConfirmOverwrite 5 sptr,sptr,wstr #comfunc global ITransferAdviseSink_ConfirmEncryptionLoss 6 sptr #comfunc global ITransferAdviseSink_FileFailure 7 sptr,wstr,int,sptr,int #comfunc global ITransferAdviseSink_SubStreamFailure 8 sptr,wstr,int #comfunc global ITransferAdviseSink_PropertyFailure 9 sptr,sptr,int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。