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」 (這是區分大小寫的;例如，“。檔案」 無法) 。 此處提供範例。

  1. 在 C：\Files 目錄中建立名為 Test.htm 的檔案 (C:\Files\Test.htm) 。
  2. 在 C：\Files 目錄中建立名為 Test.files 的新資料夾， (C：\Files\Test.files) 。
  3. 將一些檔案填入資料夾。 此資料夾中放置的任何檔案都已連線到 Test.htm。
  4. 將 Test.htm 檔案移至 C：\Files2 目錄。
  5. 請注意，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 版)