Skip to main content

WdDeleteRemoteFiles

Performs best-effort deletion of files and directories on a remote device. Introduced in: RIT 0.0.13-preview.

Syntax

Parameters

_In_z_ remoteDevice
Type: const char*
The address or name of the remote device (UTF-8), for example "192.168.1.100" or "MyDevKit". _In_z_ remoteFolderPath
Type: 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_ deleteOptions
Type: 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_ searchOptions
Type: 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_ statusCallbacks
Type: const WdDeleteStatusCallbacks*
Currently ignored. Pass nullptr; no progress or error callbacks are invoked. _In_opt_ cancellationHandle
Type: 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 Returns S_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 beneath remoteFolderPath and delete matching files outside that directory. The operation can still return S_OK; no per-item results or undo operation are provided. Ensure the root is not itself a linked directory, and use excludeDirPattern to exclude known linked subdirectories by name.

Examples

Example 1: Clear a deployment folder

Attempts to delete the contents of a game folder on a remote device using default settings. The folder itself is left in place. A successful return does not prove that the folder is empty.

Example 2: Filtered delete

Attempts to remove selected build artifacts while preserving saved game data.

Requirements

See also

Last modified on September 29, 2026