> ## 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-CN/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-CN/reference/remoting/structs/wddeleteoptions) 中的 `commonRootAlias`。

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

可选。指定用于路径解析的公共根别名，以及是否尝试删除根文件夹本身。传递 `nullptr` 可在 `remoteFolderPath` 为相对路径时使用默认公共根位置，并保留根文件夹，仅删除其内容。当 `remoteFolderPath` 解析为单个文件时，将忽略 `deleteRootFolder`。

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

可选。指定用于选择要删除的文件和目录的包含/排除模式及属性筛选器。传递 `nullptr` 可包含所有项。这些选项仅在 `remoteFolderPath` 解析为文件夹时适用；当其解析为单个文件时将被忽略。

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

当前被忽略。请传递 `nullptr`；不会调用任何进度或错误回调。

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

可选。由 [WdCreateCancellationHandle](/zh-CN/reference/remoting/functions/wdcreatecancellationhandle) 创建的取消句柄，可从单独的线程将其传递给 [WdCancelRemoteDelete](/zh-CN/reference/remoting/functions/wdcancelremotedelete) 以停止客户端等待。如果不需要取消，请传递 `nullptr`。

### 返回值

类型：**HRESULT**

当终结点报告成功或客户端观察到取消时，返回 `S_OK`；否则，返回错误代码。`S_OK` 不保证每个选定的项都已被删除。有关特定于 API 的错误代码列表（包括根本原因和故障排除指南），请参阅 [XBOX PC 远程迭代 API 错误代码](/zh-CN/reference/remoting/error-codes)。

## 备注

`WdDeleteRemoteFiles` 是一个同步阻塞调用。它会等待终结点结果、错误，或通过 [WdCancelRemoteDelete](/zh-CN/reference/remoting/functions/wdcancelremotedelete) 观察到的取消。删除是尽力而为的：不返回每项的结果，文件删除失败仅在终结点日志中报告。

若要启用取消，请在调用 `WdDeleteRemoteFiles` 之前使用 [WdCreateCancellationHandle](/zh-CN/reference/remoting/functions/wdcreatecancellationhandle) 创建 [WdCancellationHandle](/zh-CN/reference/remoting/structs/wdcancellationhandle)，然后从单独的线程将其传递给 [WdCancelRemoteDelete](/zh-CN/reference/remoting/functions/wdcancelremotedelete)。`WdDeleteRemoteFiles` 返回后，使用 [WdCloseCancellationHandle](/zh-CN/reference/remoting/functions/wdclosecancellationhandle) 关闭该句柄。

取消会停止客户端等待，而不会停止已在终结点上开始的删除。观察到取消时，调用将返回 `S_OK`，而不确认终结点是否已完成。

默认情况下，仅删除 `remoteFolderPath` 的内容，文件夹本身保留不变。将 [WdDeleteOptions](/zh-CN/reference/remoting/structs/wddeleteoptions) 中的 `deleteRootFolder` 设置为 `true`，可在删除文件夹内容后同时尝试删除该文件夹。删除文件夹是尽力而为的，并且仅在文件夹为空时才会尝试；如果经过筛选的删除留下了某些项，则会保留该文件夹。

无论 `deleteRootFolder` 如何设置，该操作还会尝试删除通过目录筛选器的空子目录，包括原本就为空的目录。

如果 `remoteFolderPath` 是绝对路径，则忽略 [WdDeleteOptions](/zh-CN/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-CN/reference/remoting/functions/wdcancelremotedelete)
* [WdCancellationHandle](/zh-CN/reference/remoting/structs/wdcancellationhandle)
* [WdCreateCancellationHandle](/zh-CN/reference/remoting/functions/wdcreatecancellationhandle)
* [WdCloseCancellationHandle](/zh-CN/reference/remoting/functions/wdclosecancellationhandle)
* [WdDeleteOptions](/zh-CN/reference/remoting/structs/wddeleteoptions)
* [WdDeleteSearchOptions](/zh-CN/reference/remoting/structs/wddeletesearchoptions)
* [WdDeleteStatusCallbacks](/zh-CN/reference/remoting/structs/wddeletestatuscallbacks)
* [WdRemoteCopy](/zh-CN/reference/remoting/functions/wdremotecopy)
* [XBOX PC 远程迭代 API 错误代码](/zh-CN/reference/remoting/error-codes)
* [XBOX PC 远程迭代 API](/zh-CN/reference/remoting/remoteiteration_members)


## Related topics

- [WdCancelRemoteDelete](/zh-CN/reference/remoting/functions/wdcancelremotedelete.md)
- [WdDeleteFileProgressInfo](/zh-CN/reference/remoting/structs/wddeletefileprogressinfo.md)
- [WdDeleteOptions](/zh-CN/reference/remoting/structs/wddeleteoptions.md)
- [WdDeleteOperationSummary](/zh-CN/reference/remoting/structs/wddeleteoperationsummary.md)
- [WdDeleteProgressCallback](/zh-CN/reference/remoting/callbacks/wddeleteprogresscallback.md)