WdRemoteCopy
在本機 PC 與遠端裝置之間複製檔案。 推出版本: RIT 0.0.8-Preview。CopyFrom 支援起始版本: RIT 0.0.13-preview。請參閱變更歷程記錄。
語法
參數
_In_z_ remoteDevice類型:const char* 遠端裝置的主機名稱或 IP 位址 (例如
"192.168.1.100" 或 "MyDevKit")。
_In_z_ sourcePath類型:const char* 要從中複製的來源路徑 (例如複製到遠端裝置時為
"C:\\builds\\MyGame")。對於 CopyTo,這是本機路徑;對於 CopyFrom,這是遠端路徑。
_In_z_ destinationPath類型:const char* 要複製到的目的地路徑。對於
CopyTo,這是遠端路徑,可以是絕對路徑 (例如 "D:\\Games\\MyGame") 或相對於通用根目錄的路徑 (例如 "MyGame")。對於 CopyFrom,這是本機路徑。
_In_opt_ copyOptions類型:const WdCopyOptions* 選用。指定複製方向與通用根目錄別名。傳遞
nullptr 以使用預設設定 (CopyTo,若 destinationPath 是相對路徑則使用預設通用根目錄位置)。
_In_opt_ searchOptions類型:const WdCopySearchOptions* 選用。指定檔案包含/排除模式和屬性篩選條件 (例如在
CopyTo 中使用 "*.exe;*.dll" 只複製可執行檔)。對於 CopyFrom,名稱模式不會限制遠端檔案的選取。傳遞 nullptr 以複製所有檔案。
_In_opt_ statusCallbacks類型:const WdCopyStatusCallbacks* 選用。指定在複製作業期間接收進度更新和診斷訊息的回呼函式。傳遞
nullptr 則不接收任何回呼。
_In_opt_ cancellationHandle類型:WdCancellationHandle 選用。由 WdCreateCancellationHandle 建立的取消控制代碼,可從另一個執行緒傳遞給 WdCancelRemoteCopy 以取消複製作業。如果不需要取消功能,請傳遞
nullptr。
傳回值
類型:HRESULT 如果成功,則傳回S_OK;否則傳回錯誤碼。
錯誤碼
備註
WdRemoteCopy 是同步的封鎖呼叫。在所有檔案都已複製、作業透過 WdCancelRemoteCopy 取消,或發生錯誤之前,它都不會傳回。
若要啟用取消功能,請在呼叫 WdRemoteCopy 之前使用 WdCreateCancellationHandle 建立 WdCancellationHandle,然後從另一個執行緒將它傳遞給 WdCancelRemoteCopy。WdRemoteCopy 傳回之後,請使用 WdCloseCancellationHandle 關閉控制代碼。
使用 WdCopyDirection::CopyTo 將檔案從本機 PC 推送到遠端裝置,或使用 CopyFrom 將檔案從遠端裝置提取到本機 PC。預設方向為 CopyTo。
對於 CopyTo,遠端路徑是 destinationPath;對於 CopyFrom,遠端路徑是 sourcePath。如果該路徑是絕對路徑,則會忽略 WdCopyOptions 中的 commonRootAlias。如果是相對路徑,除非指定了 commonRootAlias,否則會使用預設的通用根目錄位置。
若要在複製期間接收進度更新,請提供含有回呼函式指標的 WdCopyStatusCallbacks 結構。
WdRemoteCopy 不會在失敗時自動重試。如果作業因網路中斷而失敗,呼叫端必須重新叫用 WdRemoteCopy。失敗前已成功複製的檔案會保留在目的地上;差異複製行為可確保重試時只會重新傳輸未完成或遺失的檔案。沒有逾時設定;複製會持續進行,直到完成、發生錯誤或被取消為止。
