> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WdDeleteRemoteFiles

> WdDeleteRemoteFiles 的參考資料，此函式會盡力刪除遠端裝置上的檔案和目錄，包含語法、參數和備註。

# WdDeleteRemoteFiles

盡力刪除遠端裝置上的檔案和目錄。

**引進版本：** [RIT 0.0.13-preview](/zh-TW/reference/remoting/release-versions#release-versions)。

## 語法

```cpp theme={null}
HRESULT WdDeleteRemoteFiles(  
         _In_z_ const char* remoteDevice,  
         _In_z_ const char* remoteFolderPath,  
         _In_opt_ const WdDeleteOptions* deleteOptions,  
         _In_opt_ const WdDeleteSearchOptions* searchOptions,  
         _In_opt_ const WdDeleteStatusCallbacks* statusCallbacks,  
         _In_opt_ WdCancellationHandle cancellationHandle  
);  
```

### 參數

`_In_z_ remoteDevice`\
類型：**const char\***

遠端裝置的位址或名稱 (UTF-8)，例如 `"192.168.1.100"` 或 `"MyDevKit"`。

`_In_z_ remoteFolderPath`\
類型：**const char\***

遠端裝置上要刪除的路徑 (UTF-8)。這可以是資料夾路徑 (此時會刪除其內容)，也可以是單一檔案路徑 (此時只會刪除該檔案)。如果 `remoteFolderPath` 是絕對路徑，則會忽略 [WdDeleteOptions](/zh-TW/reference/remoting/structs/wddeleteoptions) 中的 `commonRootAlias`。

`_In_opt_ deleteOptions`\
類型：**const [WdDeleteOptions](/zh-TW/reference/remoting/structs/wddeleteoptions)\***

選用。指定用於路徑解析的通用根目錄別名，以及是否嘗試移除根資料夾本身。傳遞 `nullptr`，即可在 `remoteFolderPath` 為相對路徑時使用預設的通用根目錄位置，並保留根資料夾，只刪除其內容。當 `remoteFolderPath` 解析為單一檔案時，會忽略 `deleteRootFolder`。

`_In_opt_ searchOptions`\
類型：**const [WdDeleteSearchOptions](/zh-TW/reference/remoting/structs/wddeletesearchoptions)\***

選用。指定用於選取要刪除哪些檔案和目錄的包含/排除模式及屬性篩選條件。傳遞 `nullptr` 以包含所有項目。這些選項只在 `remoteFolderPath` 解析為資料夾時適用；當它解析為單一檔案時會被忽略。

`_In_opt_ statusCallbacks`\
類型：**const [WdDeleteStatusCallbacks](/zh-TW/reference/remoting/structs/wddeletestatuscallbacks)\***

目前會被忽略。請傳遞 `nullptr`；不會叫用任何進度或錯誤回呼。

`_In_opt_ cancellationHandle`\
類型：**[WdCancellationHandle](/zh-TW/reference/remoting/structs/wdcancellationhandle)**

選用。由 [WdCreateCancellationHandle](/zh-TW/reference/remoting/functions/wdcreatecancellationhandle) 建立的取消控制代碼，可從另一個執行緒傳遞給 [WdCancelRemoteDelete](/zh-TW/reference/remoting/functions/wdcancelremotedelete) 以停止用戶端等候。如果不需要取消，請傳遞 `nullptr`。

### 傳回值

類型：**HRESULT**

當端點回報成功或用戶端觀察到取消時，傳回 `S_OK`；否則傳回錯誤碼。`S_OK` 並不保證每個選取的項目都已刪除。如需 API 特有錯誤碼的清單 (包括根本原因和疑難排解指引)，請參閱 [XBOX PC Remote Iteration API 錯誤碼](/zh-TW/reference/remoting/error-codes)。

## 備註

`WdDeleteRemoteFiles` 是同步的封鎖呼叫。它會等候端點結果、錯誤，或透過 [WdCancelRemoteDelete](/zh-TW/reference/remoting/functions/wdcancelremotedelete) 觀察到的取消。刪除是盡力而為：不會傳回個別項目的結果，檔案刪除失敗只會在端點記錄中回報。

若要啟用取消，請在呼叫 `WdDeleteRemoteFiles` 之前使用 [WdCreateCancellationHandle](/zh-TW/reference/remoting/functions/wdcreatecancellationhandle) 建立 [WdCancellationHandle](/zh-TW/reference/remoting/structs/wdcancellationhandle)，然後從另一個執行緒將它傳遞給 [WdCancelRemoteDelete](/zh-TW/reference/remoting/functions/wdcancelremotedelete)。`WdDeleteRemoteFiles` 傳回之後，請使用 [WdCloseCancellationHandle](/zh-TW/reference/remoting/functions/wdclosecancellationhandle) 關閉控制代碼。

取消會停止用戶端等候，而不是停止端點上已開始的刪除。觀察到取消時，呼叫會傳回 `S_OK`，而不會確認端點是否完成。

根據預設，只會刪除 `remoteFolderPath` 的內容，資料夾本身會保留。將 [WdDeleteOptions](/zh-TW/reference/remoting/structs/wddeleteoptions) 中的 `deleteRootFolder` 設定為 `true`，即可在刪除其內容後也嘗試移除該資料夾。移除是盡力而為，且只會在資料夾變成空的時候才嘗試；經過篩選的刪除若留下項目，則會保留該資料夾。

無論 `deleteRootFolder` 為何，此作業也會嘗試移除通過目錄篩選條件的空子目錄，包括原本就是空的目錄。

如果 `remoteFolderPath` 是絕對路徑，則會忽略 [WdDeleteOptions](/zh-TW/reference/remoting/structs/wddeleteoptions) 中的 `commonRootAlias`。如果 `remoteFolderPath` 是相對路徑，除非指定了 `commonRootAlias`，否則會使用預設的通用根目錄位置。

> \[!WARNING]
> 刪除可能會跟隨 `remoteFolderPath` 下的目錄連接點和目錄符號連結，並刪除該目錄之外的相符檔案。此作業仍可能傳回 `S_OK`；不會提供個別項目的結果或復原作業。請確定根目錄本身不是連結的目錄，並使用 `excludeDirPattern` 依名稱排除已知的連結子目錄。

## 範例

### 範例 1：清除部署資料夾

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

```cpp theme={null}
// BasicDelete.cpp
// Clears the contents of a deployment folder on a remote device.
// Build: Link against wdremoteapi.lib

#include <windows.h>
#include <stdio.h>
#include "WdRemoteIteration.h"

int main()
{
    // TODO: Replace with your remote device IP address or hostname
    const char* remoteDevice = "192.168.1.100";

    // TODO: Replace with the folder name on the remote device.
    // Relative paths resolve against the default common root.
    const char* remoteFolderPath = "MyGame";

    HRESULT hr = WdDeleteRemoteFiles(
        remoteDevice,
        remoteFolderPath,
        nullptr,    // deleteOptions — default common root, folder itself is kept
        nullptr,    // searchOptions - selects all items
        nullptr,    // statusCallbacks - currently ignored
        nullptr);   // cancellationHandle — no cancellation support

    if (SUCCEEDED(hr))
    {
        printf("Delete request completed. Some items may remain.\n");
    }
    else
    {
        printf("Delete failed: HRESULT 0x%08X\n", hr);
    }

    return hr;
}
```

### 範例 2：經過篩選的刪除

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

```cpp theme={null}
// FilteredDelete.cpp
// Deletes selected build artifacts.
// Build: Link against wdremoteapi.lib

#include <windows.h>
#include <stdio.h>
#include "WdRemoteIteration.h"

int main()
{
    const char* remoteDevice     = "192.168.1.100";
    const char* remoteFolderPath = "MyGame";

    // Remove executables and symbols, but keep save data
    WdDeleteSearchOptions searchOptions = {};
    searchOptions.includeFilePattern    = "*.exe;*.dll;*.pdb";
    searchOptions.excludeFilePattern    = "*.sav";
    searchOptions.excludeDirPattern     = "SaveData";
    searchOptions.includeFileAttributes = 0;  // No attribute-based include filter
    searchOptions.excludeFileAttributes = 0;  // No attribute-based exclude filter
    searchOptions.includeDirAttributes  = 0;  // No attribute-based include filter
    searchOptions.excludeDirAttributes  = 0;  // No attribute-based exclude filter

    HRESULT hr = WdDeleteRemoteFiles(
        remoteDevice,
        remoteFolderPath,
        nullptr,          // deleteOptions — defaults
        &searchOptions,
        nullptr,          // statusCallbacks - currently ignored
        nullptr);         // cancellationHandle — no cancellation support

    if (SUCCEEDED(hr))
    {
        printf("Delete request completed. Some items may remain.\n");
    }
    else
    {
        printf("Delete failed: HRESULT 0x%08X\n", hr);
    }

    return hr;
}
```

## 需求

| 需求 | 值 |
| - | - |
| **標頭** | WdRemoteIteration.h |
| **程式庫** | wdremoteapi.lib |
| **支援的作業系統** | Windows 11 及更新版本 |
| **支援的架構** | x64、ARM64 |

## 另請參閱

* [WdCancelRemoteDelete](/zh-TW/reference/remoting/functions/wdcancelremotedelete)
* [WdCancellationHandle](/zh-TW/reference/remoting/structs/wdcancellationhandle)
* [WdCreateCancellationHandle](/zh-TW/reference/remoting/functions/wdcreatecancellationhandle)
* [WdCloseCancellationHandle](/zh-TW/reference/remoting/functions/wdclosecancellationhandle)
* [WdDeleteOptions](/zh-TW/reference/remoting/structs/wddeleteoptions)
* [WdDeleteSearchOptions](/zh-TW/reference/remoting/structs/wddeletesearchoptions)
* [WdDeleteStatusCallbacks](/zh-TW/reference/remoting/structs/wddeletestatuscallbacks)
* [WdRemoteCopy](/zh-TW/reference/remoting/functions/wdremotecopy)
* [XBOX PC Remote Iteration API 錯誤碼](/zh-TW/reference/remoting/error-codes)
* [XBOX PC Remote Iteration API](/zh-TW/reference/remoting/remoteiteration_members)


## Related topics

- [WdDeleteRemoteFiles](/reference/remoting/functions/wddeleteremotefiles.md)
- [WdCancelRemoteDelete](/reference/remoting/functions/wdcancelremotedelete.md)
- [WdDeleteFileProgressInfo](/reference/remoting/structs/wddeletefileprogressinfo.md)
- [WdDeleteOptions](/reference/remoting/structs/wddeleteoptions.md)
- [WdDeleteOperationSummary](/reference/remoting/structs/wddeleteoperationsummary.md)