WdRemoteCopy
Copies files between a local PC and a remote device.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).
_In_z_ destinationPathType: 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_ 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). 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.
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.
