Skip to main content

WdRemoteCopy

Copies files between a local PC and a remote device.

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). _In_z_ destinationPath
Type: const char*
The destination path to copy to. Can be an absolute path (e.g., "D:\\Games\\MyGame") or a relative path that resolves against the common root (e.g., "MyGame"). _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). 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. The function will support bidirectional copy, however CopyFrom is currently not implemented and will return E_NOTIMPL if used. Use WdCopyDirection::CopyTo to push files from the local PC to the remote device. The default direction is CopyTo. If destinationPath is an absolute path, the commonRootAlias in WdCopyOptions is ignored. If destinationPath is a relative path, 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.

Requirements

See also

Last modified on August 20, 2026