Skip to main content

WdRemoteCopy

Copies files between a local PC and a remote device. Introduced in: RIT 0.0.8-Preview. CopyFrom supported from: RIT 0.0.13-preview. See Change history.

Syntax

Parameters

_In_z_ remoteDevice
Type: const char*
The hostname or IP address of the remote device (e.g., "192.168.1.100" or "MyDevKit"). _In_z_ sourcePath
Type: const char*
The source path to copy from (e.g., "C:\\builds\\MyGame" when copying to a remote device). This is a local path for CopyTo and a remote path for CopyFrom. _In_z_ destinationPath
Type: const char*
The destination path to copy to. For CopyTo, this is a remote path and can be absolute (e.g., "D:\\Games\\MyGame") or relative to the common root (e.g., "MyGame"). For CopyFrom, this is a local path. _In_opt_ copyOptions
Type: const WdCopyOptions*
Optional. Specifies the copy direction and common root alias. Pass nullptr to use default settings (CopyTo, default common root location if destinationPath is a relative path). _In_opt_ searchOptions
Type: const WdCopySearchOptions*
Optional. Specifies file include/exclude patterns and attribute filters (e.g., "*.exe;*.dll" to copy only executables with CopyTo). For CopyFrom, name patterns do not restrict remote file selection. Pass nullptr to copy all files. _In_opt_ statusCallbacks
Type: const WdCopyStatusCallbacks*
Optional. Specifies callback functions for receiving progress updates and diagnostic messages during the copy operation. Pass nullptr to receive no callbacks. _In_opt_ cancellationHandle
Type: WdCancellationHandle
Optional. A cancellation handle created by WdCreateCancellationHandle that can be passed to WdCancelRemoteCopy from a separate thread to cancel the copy operation. Pass nullptr if cancellation is not needed.

Return value

Type: HRESULT Returns S_OK if successful; otherwise, returns an error code.

Error codes

Remarks

WdRemoteCopy is a synchronous, blocking call. It does not return until all files have been copied, the operation is cancelled via WdCancelRemoteCopy, or an error occurs. To enable cancellation, create a WdCancellationHandle using WdCreateCancellationHandle before calling WdRemoteCopy, then pass it to WdCancelRemoteCopy from a separate thread. After WdRemoteCopy returns, close the handle with WdCloseCancellationHandle. Use WdCopyDirection::CopyTo to push files from the local PC to the remote device, or CopyFrom to pull files from the remote device to the local PC. The default direction is CopyTo. The remote path is destinationPath for CopyTo and sourcePath for CopyFrom. If that path is absolute, the commonRootAlias in WdCopyOptions is ignored. If it is relative, the default common root location is used unless a commonRootAlias is specified. To receive progress updates during the copy, provide a WdCopyStatusCallbacks structure with callback function pointers.
Only one WdRemoteCopy call may be active at a time, regardless of target device or destination path. Calling WdRemoteCopy while another copy is already in progress results in undefined behavior.
WdRemoteCopy does not automatically retry on failure. If the operation fails due to a network interruption, the caller must re-invoke WdRemoteCopy. Files that were successfully copied before the failure remain on the destination — delta copy behavior ensures that only incomplete or missing files are re-transferred on retry. There is no timeout; the copy continues until completion, an error occurs, or it is cancelled.

Examples

Example 1: Basic file copy

Copies a local build folder to a remote device using default settings. All files are copied with no filtering, progress reporting, or cancellation support.

Example 2: Filtered copy with progress reporting

Copies only specific file types while skipping debug artifacts and intermediate directories. A progress callback prints live transfer status to the console.

Change history

Requirements

See also

Last modified on October 19, 2026