> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WdRemoteCopy

> WdRemoteCopy

# WdRemoteCopy

로컬 PC와 원격 기기 간에 파일을 복사합니다.

## 구문

```cpp theme={null}
HRESULT WdRemoteCopy(  
         _In_z_ const char* remoteDevice,  
         _In_z_ const char* sourcePath,  
         _In_z_ const char* destinationPath,  
         _In_opt_ const WdCopyOptions* copyOptions,  
         _In_opt_ const WdCopySearchOptions* searchOptions,  
         _In_opt_ const WdCopyStatusCallbacks* statusCallbacks,  
         _In_opt_ WdCancellationHandle cancellationHandle  
);  
```

### 매개 변수

`_In_z_ remoteDevice`\
형식: **const char\***

원격 기기의 호스트 이름 또는 IP 주소입니다(예: `"192.168.1.100"` 또는 `"MyDevKit"`).

`_In_z_ sourcePath`\
형식: **const char\***

복사할 원본 경로입니다(예: 원격 기기로 복사할 때는 `"C:\\builds\\MyGame"`).

`_In_z_ destinationPath`\
형식: **const char\***

복사할 대상 경로입니다. 절대 경로(예: `"D:\\Games\\MyGame"`)이거나 공통 루트를 기준으로 확인되는 상대 경로(예: `"MyGame"`)일 수 있습니다.

`_In_opt_ copyOptions`\
형식: **const [WdCopyOptions](/reference/remoting/structs/wdcopyoptions)\***

선택 사항. 복사 방향과 공통 루트 별칭을 지정합니다. 기본 설정(`CopyTo`, `destinationPath`가 상대 경로인 경우 기본 공통 루트 위치)을 사용하려면 `nullptr`을 전달하세요.

`_In_opt_ searchOptions`\
형식: **const [WdCopySearchOptions](/reference/remoting/structs/wdcopysearchoptions)\***

선택 사항. 파일 포함/제외 패턴과 특성 필터를 지정합니다(예: 실행 파일만 복사하려면 `"*.exe;*.dll"`). 모든 파일을 복사하려면 `nullptr`을 전달하세요.

`_In_opt_ statusCallbacks`\
형식: **const [WdCopyStatusCallbacks](/reference/remoting/structs/wdcopystatuscallbacks)\***

선택 사항. 복사 작업 중 진행률 업데이트와 진단 메시지를 받기 위한 콜백 함수를 지정합니다. 콜백을 받지 않으려면 `nullptr`을 전달하세요.

`_In_opt_ cancellationHandle`\
형식: **[WdCancellationHandle](/reference/remoting/structs/wdcancellationhandle)**

선택 사항. [WdCreateCancellationHandle](/reference/remoting/functions/wdcreatecancellationhandle)로 생성된 취소 핸들이며, 복사 작업을 취소하기 위해 별도의 스레드에서 [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy)에 전달할 수 있습니다. 취소가 필요하지 않으면 `nullptr`을 전달하세요.

### 반환 값

형식: **HRESULT**

성공 시 `S_OK`를 반환하고, 그렇지 않으면 오류 코드를 반환합니다.

#### 오류 코드

| 코드                      | 값          | 설명                             | 근본 원인                                                                             | 문제 해결                                                                                                   |
| ----------------------- | ---------- | ------------------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| E\_CONNECTIONERROR      | 0x8C114014 | 연결 오류입니다.                      | 네트워크 연결을 설정할 때의 일반적인 실패(전송 계층 오류)이며, IP 주소 유효성이나 원격 컴퓨터 이름 확인과는 무관합니다.            | 네트워크 연결, 방화벽 규칙, 원격 컴퓨터의 서비스 가용성을 확인합니다. 기기 간 가시성을 확인하고, 서로 ping이 가능해야 합니다. 로깅을 활성화한 상태에서 연결을 다시 시도합니다. |
| E\_NAMERESOLUTIONFAILED | 0x8C114012 | 원격 컴퓨터 이름을 확인할 수 없습니다.         | DNS 또는 로컬 이름 확인을 통해 호스트 이름을 확인할 수 없습니다.                                           | 호스트 이름 철자, DNS 구성 및 네트워크 연결을 확인합니다. 이름 확인 문제를 분리하려면 IP 주소를 사용합니다.                                       |
| E\_INVALIDADDRESS       | 0x8C114013 | 잘못된 주소입니다.                     | 잘못되었거나 형식이 맞지 않거나 지원되지 않는 네트워크 주소가 제공되었습니다(예: 잘못된 IP 형식, 잘못된 IP 또는 지원되지 않는 프로토콜). | 올바른 IP 주소인지 확인합니다. 주소 형식을 수정하고 IPv4 프로토콜을 사용하는지 확인합니다.                                                  |
| E\_CLIENTNOTAUTHORIZED  | 0x8C114008 | 기기가 클라이언트를 거부했습니다.             | 클라이언트가 기기의 신뢰할 수 있는 클라이언트 목록에 없습니다. 페어링 프로세스를 완료하기 전에 연결 시도가 시작되었습니다.             | pin 페어링 프로세스를 성공적으로 완료합니다. 연결 요청을 다시 실행합니다.                                                             |
| E\_SERVERNOTAUTHORIZED  | 0x8C114009 | 클라이언트가 기기를 거부했습니다.             | 대상 기기가 클라이언트의 신뢰할 수 있는 엔드포인트 목록에 없습니다. 페어링 프로세스를 완료하기 전에 연결 시도가 시작되었습니다.          | pin 페어링 프로세스를 성공적으로 완료합니다. 연결 요청을 다시 실행합니다.                                                             |
| E\_SERVERTOOOLD         | 0x8C114011 | 이 클라이언트에 대해 서버 버전이 너무 오래되었습니다. | 클라이언트 측 API 버전이 원격 기기의 엔드포인트 버전보다 최신입니다.                                          | 원격 컴퓨터의 wdEndpoint를 호환되는 버전으로 업데이트합니다.                                                                  |
| E\_ADMIN\_REQUIRED      | 0x8C114016 | 관리자 권한이 필요합니다.                 | 엔드포인트가 상승된 권한으로 실행 중이 아니며 작업에 관리자 수준 권한이 필요합니다.                                   | 관리자로 엔드포인트를 다시 실행합니다.                                                                                   |

## 설명

`WdRemoteCopy`는 동기 블로킹 호출입니다. 모든 파일이 복사되거나, [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy)를 통해 작업이 취소되거나, 오류가 발생할 때까지 반환되지 않습니다.

취소를 활성화하려면 `WdRemoteCopy`를 호출하기 전에 [WdCreateCancellationHandle](/reference/remoting/functions/wdcreatecancellationhandle)을 사용해 [WdCancellationHandle](/reference/remoting/structs/wdcancellationhandle)을 생성한 다음, 별도의 스레드에서 [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy)에 전달하세요. `WdRemoteCopy`가 반환된 후에는 [WdCloseCancellationHandle](/reference/remoting/functions/wdclosecancellationhandle)로 핸들을 닫으세요.

이 함수는 양방향 복사를 지원할 예정이지만, CopyFrom은 현재 구현되지 않았으며 사용 시 E\_NOTIMPL을 반환합니다. 로컬 PC에서 원격 기기로 파일을 푸시하려면 [WdCopyDirection::CopyTo](/reference/remoting/enums/wdcopydirection)를 사용하세요. 기본 방향은 `CopyTo`입니다.

`destinationPath`가 절대 경로이면 [WdCopyOptions](/reference/remoting/structs/wdcopyoptions)의 `commonRootAlias`는 무시됩니다. `destinationPath`가 상대 경로이면 `commonRootAlias`가 지정되지 않은 경우 기본 공통 루트 위치가 사용됩니다.

복사 중 진행률 업데이트를 받으려면 콜백 함수 포인터가 포함된 [WdCopyStatusCallbacks](/reference/remoting/structs/wdcopystatuscallbacks) 구조체를 제공하세요.

<Info>대상 기기나 대상 경로에 관계없이 한 번에 하나의 `WdRemoteCopy` 호출만 활성화할 수 있습니다. 다른 복사가 이미 진행 중일 때 `WdRemoteCopy`를 호출하면 정의되지 않은 동작이 발생합니다.</Info>

`WdRemoteCopy`는 실패 시 자동으로 재시도하지 않습니다. 네트워크 중단으로 인해 작업이 실패한 경우, 호출자는 `WdRemoteCopy`를 다시 호출해야 합니다. 실패 이전에 성공적으로 복사된 파일은 대상에 남아 있습니다. 델타 복사 동작 덕분에 재시도 시 불완전하거나 누락된 파일만 다시 전송됩니다. 시간 초과는 없습니다. 완료되거나, 오류가 발생하거나, 취소될 때까지 복사가 계속됩니다.

## 예제

### 예제 1: 기본 파일 복사

기본 설정을 사용하여 로컬 빌드 폴더를 원격 기기로 복사합니다. 필터링, 진행률 보고 또는 취소 지원 없이 모든 파일이 복사됩니다.

```cpp theme={null}
// BasicCopy.cpp
// 로컬 빌드 폴더를 원격 기기로 복사합니다.
// 빌드: wdremoteapi.lib에 링크

#include <windows.h>
#include <stdio.h>
#include "WdRemoteIteration.h"

int main()
{
    // TODO: 원격 기기의 IP 주소 또는 호스트 이름으로 바꾸세요
    const char* remoteDevice = "192.168.1.100";

    // TODO: 로컬 빌드 출력 경로로 바꾸세요
    const char* sourcePath = "C:\\builds\\MyGame";

    // TODO: 원격 기기에서 원하는 폴더 이름으로 바꾸세요.
    // 상대 경로는 기본 공통 루트를 기준으로 확인됩니다.
    const char* destinationPath = "MyGame";

    HRESULT hr = WdRemoteCopy(
        remoteDevice,
        sourcePath,
        destinationPath,
        nullptr,    // copyOptions — 기본값: CopyTo 방향, 기본 공통 루트
        nullptr,    // searchOptions — 모든 파일 복사
        nullptr,    // statusCallbacks — 진행률 보고 없음
        nullptr);   // cancellationHandle — 취소 지원 없음

    if (SUCCEEDED(hr))
    {
        printf("Copy completed successfully.\n");
    }
    else
    {
        printf("Copy failed: HRESULT 0x%08X\n", hr);
    }

    return hr;
}
```

### 예제 2: 진행률 보고와 함께 필터링된 복사

디버그 아티팩트와 중간 디렉터리를 건너뛰면서 특정 파일 형식만 복사합니다. 진행률 콜백은 실시간 전송 상태를 콘솔에 출력합니다.

```cpp theme={null}
// FilteredCopyWithProgress.cpp
// 선택된 파일 형식을 실시간 진행률 출력과 함께 복사합니다.
// 빌드: wdremoteapi.lib에 링크

#include <windows.h>
#include <stdio.h>
#include "WdRemoteIteration.h"

HRESULT OnProgress(
    size_t fileProgressCount,
    const WdCopyFileProgressInfo* fileUpdates,
    const WdCopyOperationSummary* summary,
    void* context)
{
    if (summary->totalByteCount > 0)
    {
        double pct = (double)summary->bytesTransferredCount
                   / summary->totalByteCount * 100.0;
        printf("\rProgress: %.1f%% (%llu/%llu files)",
               pct, summary->filesCompletedCount, summary->totalFileCount);
    }
    return S_OK;  // 계속하려면 S_OK 반환; 실패 코드는 복사를 중단합니다
}

int main()
{
    const char* remoteDevice = "192.168.1.100";
    const char* sourcePath   = "C:\\builds\\MyGame";
    const char* destPath     = "MyGame";

    // 실행 파일과 데이터만 복사; 디버그 심볼과 임시 파일 건너뛰기
    WdCopySearchOptions searchOptions = {};
    searchOptions.includeFilePattern   = "*.exe;*.dll;*.ini;*.pak";
    searchOptions.excludeFilePattern   = "*.pdb;*.log;*.tmp";
    searchOptions.excludeDirPattern    = ".vs;obj;Temp;Intermediate";
    searchOptions.includeFileAttributes = 0;  // 특성 기반 포함 필터 없음
    searchOptions.excludeFileAttributes = 0;  // 특성 기반 제외 필터 없음

    // 500ms마다 진행률 업데이트 수신
    WdCopyStatusCallbacks callbacks = {};
    callbacks.copyFilesStatusCallback = OnProgress;
    callbacks.refreshRateMs           = 500;
    callbacks.copyErrorCallback       = nullptr;
    callbacks.context                 = nullptr;

    HRESULT hr = WdRemoteCopy(
        remoteDevice,
        sourcePath,
        destPath,
        nullptr,          // copyOptions — 기본값
        &searchOptions,
        &callbacks,
        nullptr);         // cancellationHandle — 취소 지원 없음

    printf("\n");  // 캐리지 리턴 진행률 출력 후 개행

    if (SUCCEEDED(hr))
    {
        printf("Copy completed successfully.\n");
    }
    else
    {
        printf("Copy failed: HRESULT 0x%08X\n", hr);
    }

    return hr;
}
```

## 요구 사항

| 요구 사항       | 값                   |
| ----------- | ------------------- |
| **헤더**      | WdRemoteIteration.h |
| **라이브러리**   | wdremoteapi.lib     |
| **지원 OS**   | Windows 11 이상       |
| **지원 아키텍처** | x64, ARM64          |

## 함께 보기

* [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy)
* [WdCancellationHandle](/reference/remoting/structs/wdcancellationhandle)
* [WdCreateCancellationHandle](/reference/remoting/functions/wdcreatecancellationhandle)
* [WdCloseCancellationHandle](/reference/remoting/functions/wdclosecancellationhandle)
* [WdCopyOptions](/reference/remoting/structs/wdcopyoptions)
* [WdCopySearchOptions](/reference/remoting/structs/wdcopysearchoptions)
* [WdCopyStatusCallbacks](/reference/remoting/structs/wdcopystatuscallbacks)
* [WdCopyDirection](/reference/remoting/enums/wdcopydirection)
* [XBOX PC Remote Iteration API 오류 코드](/reference/remoting/error-codes)
* [XBOX PC Remote Iteration API](/reference/remoting/remoteiteration_members)


## Related topics

- [WdCancelRemoteCopy](/ko/reference/remoting/functions/wdcancelremotecopy.md)
- [WdCopyDirection](/ko/reference/remoting/enums/wdcopydirection.md)
- [WdCopyOptions](/ko/reference/remoting/structs/wdcopyoptions.md)
- [WdCopyErrorCallback](/ko/reference/remoting/callbacks/wdcopyerrorcallback.md)
- [WdCopyErrorSeverity](/ko/reference/remoting/enums/wdcopyerrorseverity.md)