SHFILEOPSTRUCTA 結構 (shellapi.h)

包含 SHFileOperation 函式用來執行檔案作業的資訊。

注意 從 Windows Vista 起，建議您在此函式上使用 IFileOperation 介面。

 

語法

typedef struct _SHFILEOPSTRUCTA {
  HWND         hwnd;
  UINT         wFunc;
  PCZZSTR      pFrom;
  PCZZSTR      pTo;
  FILEOP_FLAGS fFlags;
  BOOL         fAnyOperationsAborted;
  LPVOID       hNameMappings;
  PCSTR        lpszProgressTitle;
} SHFILEOPSTRUCTA, *LPSHFILEOPSTRUCTA;

成員

hwnd

類型： HWND

對話方塊的視窗控制碼，以顯示檔案作業狀態的相關資訊。

wFunc

類型： UINT

值，表示要執行的作業。 下列其中一個值：

FO_COPY

將 pFrom 成員中指定的檔案複製到 pTo 成員中指定的位置。

FO_DELETE

刪除 pFrom中指定的檔案。

FO_MOVE

將 pFrom 中指定的檔案移至 pTo中指定的位置。

FO_RENAME

重新命名 pFrom中指定的檔案。 您無法使用此旗標，使用單一函式呼叫來重新命名多個檔案。 請改用 FO_MOVE 。

pFrom

類型： PCZZTSTR

注意 此字串必須以雙 Null 結尾。

 

一或多個原始程式檔名稱的指標。 這些名稱應該是完整路徑，以防止非預期的結果。

標準 MS-DOS 萬用字元，例如 「*」， 只能在 檔案名位置中使用。 使用字串中其他位置的萬用字元會導致無法預期的結果。

雖然這個成員宣告為單一 Null 終止字串，但它實際上是可以保存多個以 Null 分隔的檔案名的緩衝區。 每個檔案名都會以單一 Null 字元終止。 姓氏會以雙 Null 字元終止， (「\0\0」) 來表示緩衝區的結尾。

pTo

類型： PCZZTSTR

注意 此字串必須以雙 Null 結尾。

 

目的地檔案或目錄名稱的指標。 如果未使用此參數，則必須將此參數設定為 Null 。 不允許萬用字元。 其使用會導致無法預期的結果。

如同 pFrom， pTo 成員也是雙 Null 終止的字串，而且處理方式大致相同。 不過， pTo 必須符合下列規格：

• 不支援萬用字元。
• 複製和移動作業可以指定不存在的目的地目錄。 在這些情況下，系統會嘗試建立它們，並通常會顯示對話方塊，詢問使用者是否要建立新的目錄。 若要隱藏此對話方塊，並讓目錄以無訊息方式建立，請在fFlags中設定FOF_NOCONFIRMMKDIR旗標。
• 針對複製和移動作業，如果 fFlags 成員指定 FOF_MULTIDESTFILES，緩衝區可以包含多個目的地檔案名。
• 以pFrom相同的方式將多個名稱封裝到pTo字串中。
• 使用完整路徑。 不禁止使用相對路徑，但可能會有無法預測的結果。

fFlags

類型： FILEOP_FLAGS

控制檔案作業的旗標。 此成員可以採用下列旗標的組合。

FOF_ALLOWUNDO

盡可能保留復原資訊。

在 Windows Vista 之前，作業只能從執行原始作業的相同進程復原。

在 Windows Vista 和更新版本中，復原的範圍是使用者會話。 在使用者會話中執行的任何進程都可以復原另一項作業。 復原狀態會保留在 Explorer.exe 進程中，只要該進程正在執行，就可以協調復原函式。

如果原始程式檔參數不包含完整路徑和檔案名，則會忽略此旗標。

FOF_CONFIRMMOUSE

未使用。

FOF_FILESONLY

如果指定萬用字元檔案名 (，則只在) 資料夾上執行作業 (不在資料夾上。) 。

FOF_MULTIDESTFILES

pTo成員會針對pFrom () 中的每個來源檔案指定一個目的地檔案，而不是一個要儲存所有來源檔案的目錄。

FOF_NOCONFIRMATION

針對顯示的任何對話方塊，以 [ 是] 回應 [全部]。

FOF_NOCONFIRMMKDIR

如果作業需要建立新目錄，請勿要求使用者確認建立新目錄。

FOF_NO_CONNECTED_ELEMENTS

5.0 版。 請勿將連接的檔案移動為群組。 只移動指定的檔案。

FOF_NOCOPYSECURITYATTRIBS

4.71 版。 請勿複製檔案的安全性屬性。 目的地檔案會接收其新資料夾的安全性屬性。

FOF_NOERRORUI

如果發生錯誤，請勿向使用者顯示對話方塊。

FOF_NORECURSEREPARSE

未使用。

FOF_NORECURSION

只在本機目錄中執行作業。 請勿以遞迴方式操作子目錄，這是預設行為。

FOF_NO_UI

Windows Vista。 以無訊息方式執行作業，向使用者顯示任何 UI。 這相當於FOF_SILENT |FOF_NOCONFIRMATION |FOF_NOERRORUI |FOF_NOCONFIRMMKDIR。

FOF_RENAMEONCOLLISION

在移動、複製或重新命名作業中，如果目標名稱的檔案已存在於目的地，請提供在移動、複製或重新命名作業中操作的檔案。

FOF_SILENT

不要顯示進度對話方塊。

FOF_SIMPLEPROGRESS

顯示進度對話方塊，但不會在操作時顯示個別檔案名。

FOF_WANTMAPPINGHANDLE

如果指定 了FOF_RENAMEONCOLLISION ，且已重新命名任何檔案，請將包含其舊名稱和新名稱的名稱對應物件指派給 hNameMappings 成員。 當不再需要此物件時，必須使用 SHFreeNameMappings 釋放此物件。

FOF_WANTNUKEWARNING

5.0 版。 如果在刪除作業期間永久終結檔案，而不是回收，則傳送警告。 此旗標會部分覆寫 FOF_NOCONFIRMATION。

fAnyOperationsAborted

類型： BOOL

當函式傳回時，如果任何檔案作業在完成之前中止，則此成員會包含 TRUE ;否則為 FALSE。 使用者可以透過 UI 手動中止作業，或者如果已設定FOF_NOERRORUI或FOF_NOCONFIRMATION旗標，系統也可以以無訊息方式中止作業。

hNameMappings

類型： LPVOID

當函式傳回時，這個成員會包含名稱對應物件的控制碼，其中包含已重新命名之檔案的舊名稱和新名稱。 只有當 fFlags 成員包含 FOF_WANTMAPPINGHANDLE 旗標時，才會使用此成員。 如需詳細資訊，請參閱。

lpszProgressTitle

類型： PCTSTR

進度對話方塊標題的指標。 這是以 Null 結尾的字串。 只有當 fFlags 包含 FOF_SIMPLEPROGRESS 旗標時，才會使用此成員。

備註

重要 您必須確定來源和目的地路徑會以雙 Null 終止。 一般字串只會以單一 Null 字元結尾。 如果您在來源或目的地成員中傳遞該值，則函式在到達字串結尾時不會察覺，而且會繼續在記憶體中讀取，直到它到達隨機的雙 Null 值為止。 這至少可能會導致緩衝區滿溢，也可能是意外刪除不相關的資料。

 

// WRONG
LPTSTR pszSource = L"C:\\Windows\\*";

// RIGHT
LPTSTR pszSource = L"C:\\Windows\\*\0";

若要考慮兩個終止的 Null 字元，請務必建立夠大的緩衝區，以保留MAX_PATH (通常包含單一終止 Null 字元) 加上 1。

無法過度說明您的路徑應一律為完整路徑。 如果 pFrom 或 pTo 成員是不合格的名稱，則目前的目錄會取自全域目前磁片磁碟機和目錄設定，如 GetCurrentDirectory 和 SetCurrentDirectory 函式所管理。

如果您未提供完整路徑，下列事實會變成相關：

• 檔案名之前缺少路徑，不會向 SHFileOperation 指出此檔案位於目前目錄的根目錄中。
• SHFileOperation不會使用 PATH 環境變數來判斷有效的路徑。
• 當 SHFileOperation 開始執行時，無法依賴此目錄來使用目前目錄的目錄。 視為目前目錄的目錄是全進程目錄，而且可以在作業執行時從另一個執行緒變更。 如果發生這種情況， SHFileOperation 的結果將無法預期。

如果 pFrom 設定為沒有完整路徑的檔案名，則刪除具有 FO_DELETE 的檔案並不會將它移至回收站，即使已設定 FOF_ALLOWUNDO 旗標也一樣。 您必須提供完整路徑，才能將檔案刪除至回收站。

SHFileOperation 在前面加上 「\？」的任何路徑上都失敗。

此結構有兩個版本：ANSI 版本 (SHFILEOPSTRUCTA) 和 UNIcode 版本 (SHFILEOPSTRUCTW) 。 Unicode 版本與 ANSI 版本相同，不同之處在于會使用寬字元字串 (LPCWSTR) 取代 ANSI 字元字串 (LPCSTR) 。 在 Windows 98 和更早版本上，僅支援 ANSI 版本。 在 Microsoft Windows NT 4.0 和更新版本上，支援此結構的 ANSI 和 Unicode 版本。 不應該直接使用 SHFILEOPSTRUCTW 和 SHFILEOPTSTRUCTA;根據應用程式是針對 ANSI 或 Unicode 進行編譯，適當的結構會由先行編譯器重新定義為 SHFILEOPSTRUCT 。

SHNAMEMAPPING 具有類似的 ANSI 和 Unicode 版本。 針對 ANSI 應用程式， hNameMappings 會指向 int ，後面接著 ANSI SHNAMEMAPPING 結構的陣列。 針對 Unicode 應用程式， hNameMappings 會指向 int ，後面接著 Unicode SHNAMEMAPPING 結構的陣列。 不過，在 Microsoft Windows NT 4.0 和更新版本上， SHFileOperation一律 會傳回一組 Unicode SHNAMEMAPPING 結構的控制碼。 如果您想要讓應用程式能夠搭配所有版本的 Windows 運作，應用程式必須採用條件式程式碼來處理名稱對應。 例如：

x = SHFileOperation(&shop);

if (fWin9x) 
    HandleAnsiNameMappings(shop.hNameMappings);
else 
    HandleUnicodeNameMappings(shop.hNameMappings);

將 hNameMappings 視為結構的指標，其成員是 UINT 值，後面接著 SHNAMEMAPPING 結構的陣列指標，如其宣告所示：

struct HANDLETOMAPPINGS 
{
    UINT              uNumberOfMappings;  // Number of mappings in the array.
    LPSHNAMEMAPPING   lpSHNameMapping;    // Pointer to the array of mappings.
};

UINT值表示陣列中的SHNAMEMAPPING結構數目。 每個 SHNAMEMAPPING 結構都包含其中一個重新命名檔案的舊路徑和新路徑。

注意 控制碼必須使用 SHFreeNameMappings釋放。

 

注意

shellapi.h 標頭會將 SHFILEOPSTRUCT 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

規格需求

最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
標頭	shellapi.h