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

# WdCopySearchOptions

> WdCopySearchOptions

# WdCopySearchOptions

指定复制操作的文件和目录筛选模式。

**引入版本：** [RIT 0.0.8-Preview](https://docs.xbox.com/zh-CN/reference/remoting/release-versions.md#release-versions)。成员类型和可用性因版本而异；请参阅[更改历史记录](#change-history)。

> [!WARNING]
>
> 对于 `CopyFrom`，名称模式仅影响本地增量枚举；它们不会限制远程文件的选择。

## 语法

```cpp theme={null}
struct WdCopySearchOptions 
{ 
    const char* includeFilePattern;
    const char* excludeFilePattern;
    const char* excludeDirPattern;
    uint32_t includeFileAttributes;
    uint32_t excludeFileAttributes;
    uint32_t includeDirectoryAttributes;
    uint32_t excludeDirectoryAttributes;
};
```

### 成员

`_In_z_ includeFilePattern`\
类型：**const char\***

指定要在复制操作中包含哪些文件的 glob 模式（例如 `"*"` 表示包含所有文件，或 `"*.exe;*.dll"` 表示只包含可执行文件和 DLL）。

`_In_z_ excludeFilePattern`\
类型：**const char\***

指定要从复制操作中排除哪些文件的 glob 模式（例如 `"*.pdb"` 表示排除调试符号）。

`_In_z_ excludeDirPattern`\
类型：**const char\***

指定要从复制操作中排除的目录名称（而非路径）的 glob 模式（例如 `".vs;obj"` 表示排除 Visual Studio 目录和生成输出目录）。

`includeFileAttributes`\
类型：**uint32\_t**

文件属性的位掩码。具有任一指定属性的文件将包含在复制中。设置为 `0` 表示不按属性筛选。有关文件属性的更多信息，请参阅[文件属性常量](https://learn.microsoft.com/windows/win32/fileio/file-attribute-constants)。

`excludeFileAttributes`\
类型：**uint32\_t**

导致文件从复制中排除的文件属性位掩码。设置为 `0` 表示不按属性筛选。有关文件属性的更多信息，请参阅[文件属性常量](https://learn.microsoft.com/windows/win32/fileio/file-attribute-constants)。

`includeDirectoryAttributes`\
类型：**uint32\_t**

**引入版本：** [RIT 0.0.13-preview](https://docs.xbox.com/zh-CN/reference/remoting/release-versions.md#release-versions)。

目录属性的位掩码。具有任一指定属性的目录将包含在复制中。这与应用于目录的 `includeFileAttributes` 相同。设置为 `0` 表示不按属性筛选。

`excludeDirectoryAttributes`\
类型：**uint32\_t**

**引入版本：** [RIT 0.0.13-preview](https://docs.xbox.com/zh-CN/reference/remoting/release-versions.md#release-versions)。

导致目录从复制中排除的目录属性位掩码。这与应用于目录的 `excludeFileAttributes` 相同。设置为 `0` 表示不按属性筛选。

## 示例

以下名称模式示例使用 `CopyTo`。

**仅复制 `.exe` 和 `.dll` 文件：**

```cpp theme={null}
WdCopySearchOptions searchOptions = {
    .includeFilePattern = "*.exe;*.dll",
    .excludeFilePattern = nullptr,
    .excludeDirPattern = nullptr,
    .includeFileAttributes = 0,
    .excludeFileAttributes = 0,
    .includeDirectoryAttributes = 0,
    .excludeDirectoryAttributes = 0
};
```

**从复制中排除名为 `temp` 的目录：**

```cpp theme={null}
WdCopySearchOptions searchOptions = {
    .includeFilePattern = nullptr,
    .excludeFilePattern = nullptr,
    .excludeDirPattern = "temp",
    .includeFileAttributes = 0,
    .excludeFileAttributes = 0,
    .includeDirectoryAttributes = 0,
    .excludeDirectoryAttributes = 0
};
```

**仅复制只读文件或系统文件，并排除隐藏文件：**

```cpp theme={null}
WdCopySearchOptions searchOptions = {
    .includeFilePattern = nullptr,
    .excludeFilePattern = nullptr,
    .excludeDirPattern = nullptr,
    .includeFileAttributes = FILE_ATTRIBUTE_READONLY | FILE_ATTRIBUTE_SYSTEM,
    .excludeFileAttributes = FILE_ATTRIBUTE_HIDDEN,
    .includeDirectoryAttributes = 0,
    .excludeDirectoryAttributes = 0
};
```

**仅忽略隐藏目录：**

```cpp theme={null}
WdCopySearchOptions searchOptions = {
    .includeFilePattern = nullptr,
    .excludeFilePattern = nullptr,
    .excludeDirPattern = nullptr,
    .includeFileAttributes = 0,
    .excludeFileAttributes = 0,
    .includeDirectoryAttributes = 0,
    .excludeDirectoryAttributes = FILE_ATTRIBUTE_HIDDEN
};
```

> [!NOTE]
>
> 当包含模式与排除模式发生冲突时，排除模式优先，该文件将不会被复制。

## 备注

通过 `searchOptions` 参数将此结构传递给 [WdRemoteCopy](https://docs.xbox.com/zh-CN/reference/remoting/functions/wdremotecopy.md)，以筛选复制操作中包含的文件和目录。如果为 `searchOptions` 传递 `nullptr`，则复制所有文件，不进行任何筛选。

## 更改历史记录

| 版本 | 更改 |
| - | - |
| [RIT 0.0.13-preview](https://docs.xbox.com/zh-CN/reference/remoting/release-versions.md#release-versions) | 将 `includeFileAttributes` 和 `excludeFileAttributes` 从 `uint64_t` 更改为 `uint32_t`。添加了 `includeDirectoryAttributes` 和 `excludeDirectoryAttributes`，两者均为 `uint32_t`。 |
| [RIT 0.0.8-Preview](https://docs.xbox.com/zh-CN/reference/remoting/release-versions.md#release-versions) | 引入了三个名称模式字段和两个 `uint64_t` 文件属性掩码。 |

RIT 0.0.13-preview 中的更改改变了结构布局。请使用匹配的 API NuGet 包中的头文件和库重新生成本机调用方；不要将旧的结构布局传递给较新的 API DLL。

## 要求

| 要求 | 值 |
| - | - |
| **头文件** | WdRemoteIteration.h |
| **库** | wdremoteapi.lib |
| **支持的操作系统** | Windows 11 及更高版本 |
| **支持的体系结构** | x64、ARM64 |

## 另请参阅

* [WdRemoteCopy](https://docs.xbox.com/zh-CN/reference/remoting/functions/wdremotecopy.md)
* [XBOX PC 远程迭代 API](https://docs.xbox.com/zh-CN/reference/remoting/remoteiteration_members.md)


## Related topics

- [WdRemoteCopy](https://docs.xbox.com/zh-CN/reference/remoting/functions/wdremotecopy.md)
- [XBOX PC Remote Iteration API](https://docs.xbox.com/zh-CN/reference/remoting/remoteiteration_members.md)
- [WdCopyOptions](https://docs.xbox.com/zh-CN/reference/remoting/structs/wdcopyoptions.md)
- [WdDeleteSearchOptions](https://docs.xbox.com/zh-CN/reference/remoting/structs/wddeletesearchoptions.md)
- [WdDeleteRemoteFiles](https://docs.xbox.com/zh-CN/reference/remoting/functions/wddeleteremotefiles.md)