SHFileOperationA 函式 (shellapi.h)
複製、移動、重新命名或刪除檔案系統物件。 此函式已在 Windows Vista 中由 IFileOperation 取代。
語法
int SHFileOperationA(
[in, out] LPSHFILEOPSTRUCTA lpFileOp
);
參數
[in, out] lpFileOp
類型： LPSHFILEOPSTRUCT
SHFILEOPSTRUCT 結構的指標，其中包含此函式必須執行指定作業的資訊。 此參數必須包含不是 NULL 的有效值。 您必須負責驗證值。 如果您未驗證，您將會遇到非預期的結果。
傳回值
類型： int
如果成功，則傳回零;否則為非零。 應用程式通常應該只會檢查零或非零。
最好檢查 SHFILEOPSTRUCT 之 fAnyOperationsAborted 成員的值。 如果使用者取消作業，SHFileOperation 可能會傳回 0 表示成功。 如果您未檢查 fAnyOperationsAborted 以及傳回值，則無法知道函式已完成您要求的完整工作，而且您可能會在不正確的假設下繼續進行。
請勿將 GetLastError 與此函式的傳回值搭配使用。
若要檢查非零值以進行疑難解答，它們主要會對應至 Winerror.h 中定義的值。 不過，其數個可能的傳回值是以 Win32 之前的錯誤碼為基礎，在某些情況下，這些值會與稍後的 Winerror.h 值重疊，而不會符合其意義。 這些特定值在這裡詳述，而且對於 這些特定值 ，這些特定值應該透過Winerror.h 代碼接受這些意義。 不過，這些值會以下列警告提供：
- 這些是 Win32 之前的錯誤碼，且不再支援或定義於任何公用頭檔中。 若要使用它們，您必須自行定義它們，或與數值進行比較。
- 這些錯誤碼可能會變更，而且過去已這麼做。
- 這些值僅提供為偵錯的協助。 不應將其視為明確。
| 錯誤碼 | 值 | 意義 |
|---|---|---|
| DE_SAMEFILE | 0x71 | 來源和目的地檔案是相同的檔案。 |
| DE_MANYSRC1DEST | 0x72 | 來源緩衝區中指定了多個檔案路徑，但只有一個目的地檔案路徑。 |
| DE_DIFFDIR | 0x73 | 已指定重新命名作業，但目的地路徑是不同的目錄。 請改用移動作業。 |
| DE_ROOTDIR | 0x74 | 來源是無法移動或重新命名的根目錄。 |
| DE_OPCANCELLED | 0x75 | 此作業已由使用者取消，如果已將適當的旗標提供給 SHFileOperation，則以無訊息方式取消。 |
| DE_DESTSUBTREE | 0x76 | 目的地是來源的子樹。 |
| DE_ACCESSDENIEDSRC | 0x78 | 安全性設定拒絕存取來源。 |
| DE_PATHTOODEEP | 0x79 | 來源或目的地路徑超過或超過MAX_PATH。 |
| DE_MANYDEST | 0x7A | 此作業牽涉到多個目的地路徑，在移動作業的情況下可能會失敗。 |
| DE_INVALIDFILES | 0x7C | 來源或目的地中的路徑無效。 |
| DE_DESTSAMETREE | 0x7D | 來源和目的地具有相同的父資料夾。 |
| DE_FLDDESTISFILE | 0x7E | 目的地路徑是現有的檔案。 |
| DE_FILEDESTISFLD | 0x80 | 目的地路徑是現有的資料夾。 |
| DE_FILENAMETOOLONG | 0x81 | 檔案的名稱超過MAX_PATH。 |
| DE_DEST_IS_CDROM | 0x82 | 目的地是只讀CD-ROM，可能未格式化。 |
| DE_DEST_IS_DVD | 0x83 | 目的地是唯讀 DVD，可能未格式化。 |
| DE_DEST_IS_CDRECORD | 0x84 | 目的地是可寫入的CD-ROM，可能未格式化。 |
| DE_FILE_TOO_LARGE | 0x85 | 作業所涉及的檔案太大，無法用於目的地媒體或文件系統。 |
| DE_SRC_IS_CDROM | 0x86 | 來源是只讀的CD-ROM，可能未格式化。 |
| DE_SRC_IS_DVD | 0x87 | 來源是唯讀 DVD，可能未格式化。 |
| DE_SRC_IS_CDRECORD | 0x88 | 來源是可寫入的CD-ROM，可能未格式化。 |
| DE_ERROR_MAX | 0xB7 | 作業期間已超過MAX_PATH。 |
| 0x402 | 發生未知的錯誤。 這通常是因為來源或目的地中的路徑無效。 此錯誤不會發生在 Windows Vista 和更新版本上。 | |
| ERRORONDEST | 0x10000 | 目的地發生未指定的錯誤。 |
| DE_ROOTDIR |ERRORONDEST | 0x10074 | 目的地是根目錄，無法重新命名。 |
備註
您應該搭配此函式使用完整路徑名稱。 搭配相對路徑名稱使用它不是安全線程。
有兩個例外狀況，您無法使用 SHFileOperation 藉由指定網路路徑，將特殊資料夾從本機磁碟驅動器移至遠端電腦。 例外狀況是 [我的檔 ] (CSIDL_PERSONAL、 CSIDL_DOCUMENTS) 和 [ 我的圖片 ] 資料夾 (CSIDL_MYPICTURES) 。
當用來刪除檔案時，除非您在 lpFileOp 所指向之 SHFILEOPSTRUCT 結構的 fFlags 成員中設定FOF_ALLOWUNDO旗標，否則 SHFileOperation 會永久刪除檔案。 設定該旗標會將檔案傳送至回收站。 如果您想要直接刪除檔案，並保證檔案未放在回收站中，請使用 DeleteFile。
如果公開並註冊複製回呼處理程式，則 SHFileOperation 會呼叫它，除非您在 lpFileOp 所指向結構的 fFlags 成員中設定旗標，例如 FOF_NOCONFIRMATION。 如需實作複製回呼處理程式的詳細資訊，請參閱 ICopyHook：：CopyCallback 。
除非您在 lpFileOp 中設定 FOF_NORECURSION 旗標，否則檔案刪除是遞歸的。
連接檔案
使用 Windows 2000 或更新版本時，可以使用包含相關檔案的資料夾 來連接 HTML 檔案，例如圖形交換格式 (GIF) 影像或樣式表單。 如果啟用檔案連線，當您移動或複製 HTML 檔案時，也會移動或複製連線的資料夾及其所有檔案。 相反地，如果您使用相關檔案移動資料夾，也會移動 HTML 檔案。HTML 檔案必須具有 .htm 或 .html 擴展名。 您可以將包含相關檔案的資料夾放在與 HTML 檔案相同的資料夾中，以建立與相關檔案的連線。 包含已連線檔案的文件夾名稱必須與 HTML 檔名相同，後面接著 「_files」 或 「.files」 (這是區分大小寫的;例如，“。檔案」 無法) 。 此處提供範例。
- 在 C：\Files 目錄中建立名為 Test.htm 的檔案 (C:\Files\Test.htm) 。
- 在 C：\Files 目錄中建立名為 Test.files 的新資料夾， (C：\Files\Test.files) 。
- 將一些檔案填入資料夾。 此資料夾中放置的任何檔案都已連線到 Test.htm。
- 將 Test.htm 檔案移至 C：\Files2 目錄。
- 請注意，Test.files 目錄現在也會在 C：\Files2 目錄中找到。
默認會啟用檔案連線。 您可以藉由新增 REG_DWORD 專案 NoFileFolderConnection 來停用，如下所示：
HKEY_CURRENT_USER Software Microsoft Windows CurrentVersion Explorer NoFileFolderConnection
將 NoFileFolderConnection 設定為 1 會停用檔案連線。 如果此值設定為零或遺失，則會啟用檔案連線。
若只要移動指定的檔案和未連線的檔案，請在 lpFileOp 所指向結構的 fFlags 成員中設定FOF_NO_CONNECTED_ELEMENTS旗標。
請注意，使用名稱為 「MyFile_files」 的資料夾來定義連線可能不適用於當地語系化版本的 Windows。 “files” 一詞可能需要以當地語言中的對等字取代。
注意
shellapi.h 標頭會將SHFileOperation定義為別名，根據UNICODE預處理器常數的定義，自動選取此函式的ANSI或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | shellapi.h |
| 程式庫 | Shell32.lib |
| Dll | Shell32.dll (4.0 版或更新版本) |
| API 集合 | ext-ms-win-shell32-l1-2-1 (於 Windows 10 10.0.10240 版) |