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 远程迭代 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按名称排除已知的链接子目录。
