WdDeleteRemoteFiles
Performs best-effort deletion of files and directories on a remote device. Introduced in: RIT 0.0.13-preview.Syntax
Parameters
_In_z_ remoteDeviceType: const char* The address or name of the remote device (UTF-8), for example
"192.168.1.100" or "MyDevKit".
_In_z_ remoteFolderPathType: const char* The path on the remote device to delete (UTF-8). This may be either a folder path, in which case its contents are deleted, or a single file path, in which case only that file is deleted. If
remoteFolderPath is an absolute path, the commonRootAlias in WdDeleteOptions is ignored.
_In_opt_ deleteOptionsType: const WdDeleteOptions* Optional. Specifies the common root alias used for path resolution and whether removal of the root folder itself is attempted. Pass
nullptr to use the default common root location when remoteFolderPath is a relative path, and to leave the root folder in place so that only its contents are deleted. When remoteFolderPath resolves to a single file, deleteRootFolder is ignored.
_In_opt_ searchOptionsType: const WdDeleteSearchOptions* Optional. Specifies include/exclude patterns and attribute filters that select which files and directories are deleted. Pass
nullptr to include all items. These options apply only when remoteFolderPath resolves to a folder; they are ignored when it resolves to a single file.
_In_opt_ statusCallbacksType: const WdDeleteStatusCallbacks* Currently ignored. Pass
nullptr; no progress or error callbacks are invoked.
_In_opt_ cancellationHandleType: WdCancellationHandle Optional. A cancellation handle created by WdCreateCancellationHandle that can be passed to WdCancelRemoteDelete from a separate thread to stop the client wait. Pass
nullptr if cancellation is not needed.
Return value
Type: HRESULT ReturnsS_OK when the endpoint reports success or the client observes cancellation; otherwise, returns an error code. S_OK does not guarantee that every selected item was deleted. For the list of API-specific error codes, including root causes and troubleshooting guidance, see XBOX PC Remote Iteration API Error Codes.
Remarks
WdDeleteRemoteFiles is a synchronous, blocking call. It waits for an endpoint result, an error, or observed cancellation via WdCancelRemoteDelete. Deletion is best effort: no per-item results are returned, and file deletion failures are reported only in endpoint logs.
To enable cancellation, create a WdCancellationHandle using WdCreateCancellationHandle before calling WdDeleteRemoteFiles, then pass it to WdCancelRemoteDelete from a separate thread. After WdDeleteRemoteFiles returns, close the handle with WdCloseCancellationHandle.
Cancellation stops the client wait, not deletion already started on the endpoint. When cancellation is observed, the call returns S_OK without confirming endpoint completion.
By default only the contents of remoteFolderPath are deleted and the folder itself is left in place. Set deleteRootFolder in WdDeleteOptions to true to also attempt to remove the folder once its contents have been deleted. Removal is best effort and is attempted only if the folder is left empty; a filtered delete that leaves items behind preserves the folder.
Regardless of deleteRootFolder, the operation also attempts to remove empty subdirectories that pass the directory filters, including directories that were already empty.
If remoteFolderPath is an absolute path, the commonRootAlias in WdDeleteOptions is ignored. If remoteFolderPath is a relative path, the default common root location is used unless a commonRootAlias is specified.
[!WARNING] Deletion can follow directory junctions and directory symbolic links beneathremoteFolderPathand delete matching files outside that directory. The operation can still returnS_OK; no per-item results or undo operation are provided. Ensure the root is not itself a linked directory, and useexcludeDirPatternto exclude known linked subdirectories by name.
