Skip to main content

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,會導致未定義的行為。
WdRemoteCopy 不會在失敗時自動重試。如果作業因網路中斷而失敗,呼叫端必須重新叫用 WdRemoteCopy。失敗前已成功複製的檔案會保留在目的地上;差異複製行為可確保重試時只會重新傳輸未完成或遺失的檔案。沒有逾時設定;複製會持續進行,直到完成、發生錯誤或被取消為止。

範例

範例 1:基本檔案複製

使用預設設定將本機組建資料夾複製到遠端裝置。會複製所有檔案,不進行篩選、進度回報,也不支援取消。

範例 2:含進度回報的篩選複製

只複製特定檔案類型,同時略過偵錯成品和中繼目錄。進度回呼會將即時傳輸狀態列印到主控台。

變更歷程記錄

需求

另請參閱

Last modified on October 6, 2026