> ## 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.

# WdDeleteRemoteFiles

> Reference for WdDeleteRemoteFiles, which performs best-effort deletion of files and directories on a remote device, with syntax, parameters, and remarks.

Performs best-effort deletion of files and directories on a remote device.

**Introduced in:** [RIT 0.0.13-preview](https://docs.xbox.com/reference/remoting/release-versions.md#release-versions).

## Syntax

```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  
);  
```

### 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](https://docs.xbox.com/reference/remoting/structs/wddeleteoptions.md) is ignored.

`_In_opt_ deleteOptions`\
Type: **const [WdDeleteOptions](https://docs.xbox.com/reference/remoting/structs/wddeleteoptions.md)\***

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](https://docs.xbox.com/reference/remoting/structs/wddeletesearchoptions.md)\***

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](https://docs.xbox.com/reference/remoting/structs/wddeletestatuscallbacks.md)\***

Currently ignored. Pass `nullptr`; no progress or error callbacks are invoked.

`_In_opt_ cancellationHandle`\
Type: **[WdCancellationHandle](https://docs.xbox.com/reference/remoting/structs/wdcancellationhandle.md)**

Optional. A cancellation handle created by [WdCreateCancellationHandle](https://docs.xbox.com/reference/remoting/functions/wdcreatecancellationhandle.md) that can be passed to [WdCancelRemoteDelete](https://docs.xbox.com/reference/remoting/functions/wdcancelremotedelete.md) 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](https://docs.xbox.com/reference/remoting/error-codes.md).

## Remarks

`WdDeleteRemoteFiles` is a synchronous, blocking call. It waits for an endpoint result, an error, or observed cancellation via [WdCancelRemoteDelete](https://docs.xbox.com/reference/remoting/functions/wdcancelremotedelete.md). 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](https://docs.xbox.com/reference/remoting/structs/wdcancellationhandle.md) using [WdCreateCancellationHandle](https://docs.xbox.com/reference/remoting/functions/wdcreatecancellationhandle.md) before calling `WdDeleteRemoteFiles`, then pass it to [WdCancelRemoteDelete](https://docs.xbox.com/reference/remoting/functions/wdcancelremotedelete.md) from a separate thread. After `WdDeleteRemoteFiles` returns, close the handle with [WdCloseCancellationHandle](https://docs.xbox.com/reference/remoting/functions/wdclosecancellationhandle.md).

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](https://docs.xbox.com/reference/remoting/structs/wddeleteoptions.md) 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](https://docs.xbox.com/reference/remoting/structs/wddeleteoptions.md) 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.

```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;
}
```

### Example 2: Filtered delete

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

```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;
}
```

## Requirements

| Requirement | Value |
| - | - |
| **Header** | WdRemoteIteration.h |
| **Library** | wdremoteapi.lib |
| **Supported OS** | Windows 11 and later |
| **Supported architectures** | x64, ARM64 |

## See also

* [WdCancelRemoteDelete](https://docs.xbox.com/reference/remoting/functions/wdcancelremotedelete.md)
* [WdCancellationHandle](https://docs.xbox.com/reference/remoting/structs/wdcancellationhandle.md)
* [WdCreateCancellationHandle](https://docs.xbox.com/reference/remoting/functions/wdcreatecancellationhandle.md)
* [WdCloseCancellationHandle](https://docs.xbox.com/reference/remoting/functions/wdclosecancellationhandle.md)
* [WdDeleteOptions](https://docs.xbox.com/reference/remoting/structs/wddeleteoptions.md)
* [WdDeleteSearchOptions](https://docs.xbox.com/reference/remoting/structs/wddeletesearchoptions.md)
* [WdDeleteStatusCallbacks](https://docs.xbox.com/reference/remoting/structs/wddeletestatuscallbacks.md)
* [WdRemoteCopy](https://docs.xbox.com/reference/remoting/functions/wdremotecopy.md)
* [XBOX PC Remote Iteration API Error Codes](https://docs.xbox.com/reference/remoting/error-codes.md)
* [XBOX PC Remote Iteration API](https://docs.xbox.com/reference/remoting/remoteiteration_members.md)


## Related topics

- [WdCancelRemoteDelete](https://docs.xbox.com/reference/remoting/functions/wdcancelremotedelete.md)
- [WdDeleteFileProgressInfo](https://docs.xbox.com/reference/remoting/structs/wddeletefileprogressinfo.md)
- [WdDeleteOptions](https://docs.xbox.com/reference/remoting/structs/wddeleteoptions.md)
- [WdDeleteOperationSummary](https://docs.xbox.com/reference/remoting/structs/wddeleteoperationsummary.md)
- [WdDeleteProgressCallback](https://docs.xbox.com/reference/remoting/callbacks/wddeleteprogresscallback.md)