> ## 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

Copia arquivos entre um PC local e um dispositivo remoto.

**Introduzida em:** [RIT 0.0.8-Preview](/pt-BR/reference/remoting/release-versions#release-versions).

**Suporte a `CopyFrom` a partir de:** [RIT 0.0.13-preview](/pt-BR/reference/remoting/release-versions#release-versions). Confira o [Histórico de alterações](#change-history).

## Sintaxe

```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  
);  
```

### Parâmetros

`_In_z_ remoteDevice`\
Tipo: **const char\***

O nome do host ou o endereço IP do dispositivo remoto (por exemplo, `"192.168.1.100"` ou `"MyDevKit"`).

`_In_z_ sourcePath`\
Tipo: **const char\***

O caminho de origem da cópia (por exemplo, `"C:\\builds\\MyGame"` ao copiar para um dispositivo remoto). É um caminho local para `CopyTo` e um caminho remoto para `CopyFrom`.

`_In_z_ destinationPath`\
Tipo: **const char\***

O caminho de destino da cópia. Para `CopyTo`, é um caminho remoto e pode ser absoluto (por exemplo, `"D:\\Games\\MyGame"`) ou relativo à raiz comum (por exemplo, `"MyGame"`). Para `CopyFrom`, é um caminho local.

`_In_opt_ copyOptions`\
Tipo: **const [WdCopyOptions](/pt-BR/reference/remoting/structs/wdcopyoptions)\***

Opcional. Especifica a direção da cópia e o alias da raiz comum. Passe `nullptr` para usar as configurações padrão (`CopyTo`, local padrão da raiz comum se `destinationPath` for um caminho relativo).

`_In_opt_ searchOptions`\
Tipo: **const [WdCopySearchOptions](/pt-BR/reference/remoting/structs/wdcopysearchoptions)\***

Opcional. Especifica padrões de inclusão/exclusão de arquivos e filtros de atributos (por exemplo, `"*.exe;*.dll"` para copiar somente executáveis com `CopyTo`). Para `CopyFrom`, os padrões de nome não restringem a seleção de arquivos remotos. Passe `nullptr` para copiar todos os arquivos.

`_In_opt_ statusCallbacks`\
Tipo: **const [WdCopyStatusCallbacks](/pt-BR/reference/remoting/structs/wdcopystatuscallbacks)\***

Opcional. Especifica funções de retorno de chamada para receber atualizações de progresso e mensagens de diagnóstico durante a operação de cópia. Passe `nullptr` para não receber retornos de chamada.

`_In_opt_ cancellationHandle`\
Tipo: **[WdCancellationHandle](/pt-BR/reference/remoting/structs/wdcancellationhandle)**

Opcional. Um identificador de cancelamento criado por [WdCreateCancellationHandle](/pt-BR/reference/remoting/functions/wdcreatecancellationhandle) que pode ser passado para [WdCancelRemoteCopy](/pt-BR/reference/remoting/functions/wdcancelremotecopy) a partir de um thread separado para cancelar a operação de cópia. Passe `nullptr` se o cancelamento não for necessário.

### Valor retornado

Tipo: **HRESULT**

Retorna `S_OK` se for bem-sucedido; caso contrário, retorna um código de erro.

#### Códigos de erro

| Código | Valor | Descrição | Causa raiz | Solução de problemas |
| - | - | - | - | - |
| E\_CONNECTIONERROR | 0x8C114014 | Erro de conexão. | Falha genérica ao estabelecer a conexão de rede (falha no nível de transporte), não relacionada à validade do endereço IP nem à resolução do nome da máquina remota | Verifique a conectividade de rede, as regras de firewall e a disponibilidade do serviço na máquina remota; Verifique a visibilidade entre os dispositivos, que devem conseguir executar ping um no outro; Tente a conexão novamente com o registro em log habilitado. |
| E\_NAMERESOLUTIONFAILED | 0x8C114012 | Não foi possível resolver o nome da máquina remota. | O nome do host não pode ser resolvido via DNS ou resolução de nomes local. | Verifique a ortografia do nome do host, a configuração de DNS e a conectividade de rede.; Use o endereço IP para isolar problemas de resolução de nomes. |
| E\_INVALIDADDRESS | 0x8C114013 | Endereço inválido. | Foi fornecido um endereço de rede incorreto, malformado ou sem suporte (por exemplo, formato de IP inválido, IP errado ou protocolo sem suporte). | Confirme se o endereço IP está correto; Corrija o formato do endereço e verifique se ele usa o protocolo IPv4 |
| E\_CLIENTNOTAUTHORIZED | 0x8C114008 | O dispositivo rejeitou o cliente. | O cliente não está na lista de clientes confiáveis do dispositivo. A tentativa de conexão foi iniciada antes da conclusão do processo de emparelhamento | Conclua o processo de emparelhamento por PIN com êxito; Execute a solicitação de conexão novamente |
| E\_SERVERNOTAUTHORIZED | 0x8C114009 | O cliente rejeitou o dispositivo. | O dispositivo de destino não está na lista de pontos de extremidade confiáveis do cliente. A tentativa de conexão foi iniciada antes da conclusão do processo de emparelhamento | Conclua o processo de emparelhamento por PIN com êxito; Execute a solicitação de conexão novamente |
| E\_SERVERTOOOLD | 0x8C114011 | A versão do servidor é muito antiga para este cliente. | A versão da API no lado do cliente é mais recente que a versão do ponto de extremidade no dispositivo remoto | Atualize o wdEndpoint na máquina remota para uma versão compatível |
| E\_ADMIN\_REQUIRED | 0x8C114016 | Privilégios de administrador necessários. | O ponto de extremidade não está em execução com privilégios elevados e a operação exige permissões de nível de Administrador | Execute o ponto de extremidade novamente como Administrador |

## Comentários

`WdRemoteCopy` é uma chamada síncrona e de bloqueio. Ela só retorna quando todos os arquivos tiverem sido copiados, a operação for cancelada por meio de [WdCancelRemoteCopy](/pt-BR/reference/remoting/functions/wdcancelremotecopy) ou ocorrer um erro.

Para habilitar o cancelamento, crie um [WdCancellationHandle](/pt-BR/reference/remoting/structs/wdcancellationhandle) usando [WdCreateCancellationHandle](/pt-BR/reference/remoting/functions/wdcreatecancellationhandle) antes de chamar `WdRemoteCopy` e, em seguida, passe-o para [WdCancelRemoteCopy](/pt-BR/reference/remoting/functions/wdcancelremotecopy) a partir de um thread separado. Depois que `WdRemoteCopy` retornar, feche o identificador com [WdCloseCancellationHandle](/pt-BR/reference/remoting/functions/wdclosecancellationhandle).

Use [WdCopyDirection::CopyTo](/pt-BR/reference/remoting/enums/wdcopydirection) para enviar arquivos do PC local para o dispositivo remoto ou `CopyFrom` para obter arquivos do dispositivo remoto para o PC local. A direção padrão é `CopyTo`.

O caminho remoto é `destinationPath` para `CopyTo` e `sourcePath` para `CopyFrom`. Se esse caminho for absoluto, o `commonRootAlias` em [WdCopyOptions](/pt-BR/reference/remoting/structs/wdcopyoptions) será ignorado. Se for relativo, o local padrão da raiz comum será usado, a menos que um `commonRootAlias` seja especificado.

Para receber atualizações de progresso durante a cópia, forneça uma estrutura [WdCopyStatusCallbacks](/pt-BR/reference/remoting/structs/wdcopystatuscallbacks) com ponteiros de função de retorno de chamada.

<Warning>Somente uma chamada de `WdRemoteCopy` pode estar ativa por vez, independentemente do dispositivo de destino ou do caminho de destino. Chamar `WdRemoteCopy` enquanto outra cópia já estiver em andamento resulta em comportamento indefinido.  </Warning>
`WdRemoteCopy` não tenta novamente de forma automática em caso de falha. Se a operação falhar devido a uma interrupção de rede, o chamador deverá invocar `WdRemoteCopy` novamente. Os arquivos copiados com êxito antes da falha permanecem no destino; o comportamento de cópia delta garante que somente arquivos incompletos ou ausentes sejam transferidos novamente na nova tentativa. Não há tempo limite; a cópia continua até a conclusão, até ocorrer um erro ou até ser cancelada.

## Exemplos

### Exemplo 1: Cópia básica de arquivos

Copia uma pasta de build local para um dispositivo remoto usando as configurações padrão. Todos os arquivos são copiados sem filtragem, relatório de progresso ou suporte a cancelamento.

```cpp theme={null}
// BasicCopy.cpp
// Copies a local build folder to a remote device.
// Build: Link against wdremoteapi.lib

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

int main()
{
    // TODO: Replace with your remote device IP address or hostname
    const char* remoteDevice = "192.168.1.100";

    // TODO: Replace with the path to your local build output
    const char* sourcePath = "C:\\builds\\MyGame";

    // TODO: Replace with the desired folder name on the remote device.
    // Relative paths resolve against the default common root.
    const char* destinationPath = "MyGame";

    HRESULT hr = WdRemoteCopy(
        remoteDevice,
        sourcePath,
        destinationPath,
        nullptr,    // copyOptions — defaults to CopyTo direction, default common root
        nullptr,    // searchOptions — copies all files
        nullptr,    // statusCallbacks — no progress reporting
        nullptr);   // cancellationHandle — no cancellation support

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

    return hr;
}
```

### Exemplo 2: Cópia filtrada com relatório de progresso

Copia somente tipos de arquivo específicos, ignorando artefatos de depuração e diretórios intermediários. Um retorno de chamada de progresso imprime o status da transferência em tempo real no console.

```cpp theme={null}
// FilteredCopyWithProgress.cpp
// Copies selected file types with live progress output.
// Build: Link against 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;  // A failed callback HRESULT is logged, but does not abort the copy
}

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

    // Only copy executables and data; skip debug symbols and temp files
    WdCopySearchOptions searchOptions = {};
    searchOptions.includeFilePattern   = "*.exe;*.dll;*.ini;*.pak";
    searchOptions.excludeFilePattern   = "*.pdb;*.log;*.tmp";
    searchOptions.excludeDirPattern    = ".vs;obj;Temp;Intermediate";
    searchOptions.includeFileAttributes = 0;  // No attribute-based include filter
    searchOptions.excludeFileAttributes = 0;  // No attribute-based exclude filter

    // Request a 500 ms progress update interval
    WdCopyStatusCallbacks callbacks = {};
    callbacks.copyFilesStatusCallback = OnProgress;
    callbacks.refreshRateMs           = 500;
    callbacks.copyErrorCallback       = nullptr;
    callbacks.context                 = nullptr;

    HRESULT hr = WdRemoteCopy(
        remoteDevice,
        sourcePath,
        destPath,
        nullptr,          // copyOptions — defaults
        &searchOptions,
        &callbacks,
        nullptr);         // cancellationHandle — no cancellation support

    printf("\n");  // Newline after carriage-return progress output

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

    return hr;
}
```

## Histórico de alterações

| Versão | Alteração |
| - | - |
| [RIT 0.0.13-preview](/pt-BR/reference/remoting/release-versions#release-versions) | Implementação de `CopyFrom`. Versões anteriores retornam `E_NOTIMPL` para essa direção, embora o valor de enumeração esteja declarado. |
| [RIT 0.0.8-Preview](/pt-BR/reference/remoting/release-versions#release-versions) | Introdução de `WdRemoteCopy` com suporte a `CopyTo`. |

## Requisitos

| Requisito | Valor |
| - | - |
| **Cabeçalho** | WdRemoteIteration.h |
| **Biblioteca** | wdremoteapi.lib |
| **SO com suporte** | Windows 11 e posterior |
| **Arquiteturas com suporte** | x64, ARM64 |

## Confira também

* [WdCancelRemoteCopy](/pt-BR/reference/remoting/functions/wdcancelremotecopy)
* [WdCancellationHandle](/pt-BR/reference/remoting/structs/wdcancellationhandle)
* [WdCreateCancellationHandle](/pt-BR/reference/remoting/functions/wdcreatecancellationhandle)
* [WdCloseCancellationHandle](/pt-BR/reference/remoting/functions/wdclosecancellationhandle)
* [WdCopyOptions](/pt-BR/reference/remoting/structs/wdcopyoptions)
* [WdCopySearchOptions](/pt-BR/reference/remoting/structs/wdcopysearchoptions)
* [WdCopyStatusCallbacks](/pt-BR/reference/remoting/structs/wdcopystatuscallbacks)
* [WdCopyDirection](/pt-BR/reference/remoting/enums/wdcopydirection)
* [Códigos de erro da XBOX PC Remote Iteration API](/pt-BR/reference/remoting/error-codes)
* [XBOX PC Remote Iteration API](/pt-BR/reference/remoting/remoteiteration_members)


## Related topics

- [WdRemoteCopy](/reference/remoting/functions/wdremotecopy.md)
- [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy.md)
- [WdCopyDirection](/reference/remoting/enums/wdcopydirection.md)