Skip to main content

WdDeleteRemoteFiles

盡力刪除遠端裝置上的檔案和目錄。 引進版本: RIT 0.0.13-preview。

語法

參數

_In_z_ remoteDevice
類型:const char*
遠端裝置的位址或名稱 (UTF-8),例如 "192.168.1.100" 或 "MyDevKit"。 _In_z_ remoteFolderPath
類型:const char*
遠端裝置上要刪除的路徑 (UTF-8)。這可以是資料夾路徑 (此時會刪除其內容),也可以是單一檔案路徑 (此時只會刪除該檔案)。如果 remoteFolderPath 是絕對路徑,則會忽略 WdDeleteOptions 中的 commonRootAlias。 _In_opt_ deleteOptions
類型:const WdDeleteOptions*
選用。指定用於路徑解析的通用根目錄別名,以及是否嘗試移除根資料夾本身。傳遞 nullptr,即可在 remoteFolderPath 為相對路徑時使用預設的通用根目錄位置,並保留根資料夾,只刪除其內容。當 remoteFolderPath 解析為單一檔案時,會忽略 deleteRootFolder。 _In_opt_ searchOptions
類型:const WdDeleteSearchOptions*
選用。指定用於選取要刪除哪些檔案和目錄的包含/排除模式及屬性篩選條件。傳遞 nullptr 以包含所有項目。這些選項只在 remoteFolderPath 解析為資料夾時適用;當它解析為單一檔案時會被忽略。 _In_opt_ statusCallbacks
類型:const WdDeleteStatusCallbacks*
目前會被忽略。請傳遞 nullptr;不會叫用任何進度或錯誤回呼。 _In_opt_ cancellationHandle
類型:WdCancellationHandle
選用。由 WdCreateCancellationHandle 建立的取消控制代碼,可從另一個執行緒傳遞給 WdCancelRemoteDelete 以停止用戶端等候。如果不需要取消,請傳遞 nullptr。

傳回值

類型:HRESULT 當端點回報成功或用戶端觀察到取消時,傳回 S_OK;否則傳回錯誤碼。S_OK 並不保證每個選取的項目都已刪除。如需 API 特有錯誤碼的清單 (包括根本原因和疑難排解指引),請參閱 XBOX PC Remote Iteration API 錯誤碼。

備註

WdDeleteRemoteFiles 是同步的封鎖呼叫。它會等候端點結果、錯誤,或透過 WdCancelRemoteDelete 觀察到的取消。刪除是盡力而為:不會傳回個別項目的結果,檔案刪除失敗只會在端點記錄中回報。 若要啟用取消,請在呼叫 WdDeleteRemoteFiles 之前使用 WdCreateCancellationHandle 建立 WdCancellationHandle,然後從另一個執行緒將它傳遞給 WdCancelRemoteDelete。WdDeleteRemoteFiles 傳回之後,請使用 WdCloseCancellationHandle 關閉控制代碼。 取消會停止用戶端等候,而不是停止端點上已開始的刪除。觀察到取消時,呼叫會傳回 S_OK,而不會確認端點是否完成。 根據預設,只會刪除 remoteFolderPath 的內容,資料夾本身會保留。將 WdDeleteOptions 中的 deleteRootFolder 設定為 true,即可在刪除其內容後也嘗試移除該資料夾。移除是盡力而為,且只會在資料夾變成空的時候才嘗試;經過篩選的刪除若留下項目,則會保留該資料夾。 無論 deleteRootFolder 為何,此作業也會嘗試移除通過目錄篩選條件的空子目錄,包括原本就是空的目錄。 如果 remoteFolderPath 是絕對路徑,則會忽略 WdDeleteOptions 中的 commonRootAlias。如果 remoteFolderPath 是相對路徑,除非指定了 commonRootAlias,否則會使用預設的通用根目錄位置。
[!WARNING] 刪除可能會跟隨 remoteFolderPath 下的目錄連接點和目錄符號連結,並刪除該目錄之外的相符檔案。此作業仍可能傳回 S_OK;不會提供個別項目的結果或復原作業。請確定根目錄本身不是連結的目錄,並使用 excludeDirPattern 依名稱排除已知的連結子目錄。

範例

範例 1:清除部署資料夾

使用預設設定,嘗試刪除遠端裝置上遊戲資料夾的內容。資料夾本身會保留。成功傳回並不能證明資料夾已清空。

範例 2:經過篩選的刪除

嘗試移除選取的建置成品,同時保留遊戲存檔資料。

需求

另請參閱

Last modified on October 6, 2026