SHFILEOPSTRUCTA 結構 （shellapi.h）

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

Note 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，緩衝區可以包含多個目的地檔名。
• 將多個名稱封裝到 pTo 字串串中，與 pFrom相同。
• 使用完整路徑。 不允許使用相對路徑，但可能會產生無法預期的結果。

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