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_ remoteDeviceType: const char* The hostname or IP address of the remote device (e.g.,
"192.168.1.100" or "MyDevKit").
_In_z_ sourcePathType: 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_ destinationPathType: 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_ copyOptionsType: 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_ searchOptionsType: 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_ statusCallbacksType: 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_ cancellationHandleType: 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 ReturnsS_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.
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.
