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

Copie des fichiers entre un PC local et un appareil distant.

**Introduit dans :** [RIT 0.0.8-Preview](/fr-CA/reference/remoting/release-versions#release-versions).

**`CopyFrom` pris en charge à partir de :** [RIT 0.0.13-preview](/fr-CA/reference/remoting/release-versions#release-versions). Consultez [Historique des modifications](#change-history).

## Syntaxe

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

### Paramètres

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

Le nom d'hôte ou l'adresse IP de l'appareil distant (p. ex., `"192.168.1.100"` ou `"MyDevKit"`).

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

Le chemin source à partir duquel copier (p. ex., `"C:\\builds\\MyGame"` lors d'une copie vers un appareil distant). Il s'agit d'un chemin local pour `CopyTo` et d'un chemin distant pour `CopyFrom`.

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

Le chemin de destination vers lequel copier. Pour `CopyTo`, il s'agit d'un chemin distant qui peut être absolu (p. ex., `"D:\\Games\\MyGame"`) ou relatif à la racine commune (p. ex., `"MyGame"`). Pour `CopyFrom`, il s'agit d'un chemin local.

`_In_opt_ copyOptions`\
Type : **const [WdCopyOptions](/fr-CA/reference/remoting/structs/wdcopyoptions)\***

Facultatif. Spécifie la direction de la copie et l'alias de racine commune. Passez `nullptr` pour utiliser les paramètres par défaut (`CopyTo`, emplacement de racine commune par défaut si `destinationPath` est un chemin relatif).

`_In_opt_ searchOptions`\
Type : **const [WdCopySearchOptions](/fr-CA/reference/remoting/structs/wdcopysearchoptions)\***

Facultatif. Spécifie les modèles d'inclusion et d'exclusion de fichiers ainsi que les filtres d'attributs (p. ex., `"*.exe;*.dll"` pour copier uniquement les exécutables avec `CopyTo`). Pour `CopyFrom`, les modèles de noms ne restreignent pas la sélection des fichiers distants. Passez `nullptr` pour copier tous les fichiers.

`_In_opt_ statusCallbacks`\
Type : **const [WdCopyStatusCallbacks](/fr-CA/reference/remoting/structs/wdcopystatuscallbacks)\***

Facultatif. Spécifie les fonctions de rappel permettant de recevoir des mises à jour de progression et des messages de diagnostic pendant l'opération de copie. Passez `nullptr` pour ne recevoir aucun rappel.

`_In_opt_ cancellationHandle`\
Type : **[WdCancellationHandle](/fr-CA/reference/remoting/structs/wdcancellationhandle)**

Facultatif. Un handle d'annulation créé par [WdCreateCancellationHandle](/fr-CA/reference/remoting/functions/wdcreatecancellationhandle) qui peut être passé à [WdCancelRemoteCopy](/fr-CA/reference/remoting/functions/wdcancelremotecopy) à partir d'un thread distinct pour annuler l'opération de copie. Passez `nullptr` si l'annulation n'est pas requise.

### Valeur de retour

Type : **HRESULT**

Retourne `S_OK` en cas de réussite; sinon, retourne un code d'erreur.

#### Codes d'erreur

| Code | Valeur | Description | Cause première | Dépannage |
| - | - | - | - | - |
| E\_CONNECTIONERROR | 0x8C114014 | Erreur de connexion. | Échec générique lors de l'établissement de la connexion réseau (échec au niveau du transport), sans lien avec la validité de l'adresse IP ou la résolution du nom de l'ordinateur distant | Vérifiez la connectivité réseau, les règles du pare-feu et la disponibilité du service sur l'ordinateur distant; Vérifiez la visibilité entre les appareils, qui devraient pouvoir se joindre par ping; Relancez la connexion avec la journalisation activée. |
| E\_NAMERESOLUTIONFAILED | 0x8C114012 | Impossible de résoudre le nom de l'ordinateur distant. | Le nom d'hôte ne peut pas être résolu au moyen du DNS ou de la résolution de noms locale. | Vérifiez l'orthographe du nom d'hôte, la configuration DNS et la connectivité réseau.; Utilisez l'adresse IP pour isoler les problèmes de résolution de noms. |
| E\_INVALIDADDRESS | 0x8C114013 | Adresse non valide. | Adresse réseau fournie incorrecte, mal formée ou non prise en charge (p. ex., format IP incorrect, mauvaise adresse IP ou protocole non pris en charge). | Confirmez que l'adresse IP est la bonne; Corrigez le format de l'adresse et assurez-vous qu'elle utilise le protocole IPv4 |
| E\_CLIENTNOTAUTHORIZED | 0x8C114008 | L'appareil a rejeté le client. | Le client ne figure pas dans la liste des clients approuvés de l'appareil. La tentative de connexion a été lancée avant la fin du processus de jumelage | Terminez correctement le processus de jumelage par NIP; Exécutez de nouveau la demande de connexion |
| E\_SERVERNOTAUTHORIZED | 0x8C114009 | Le client a rejeté l'appareil. | L'appareil cible ne figure pas dans la liste des points de terminaison approuvés du client. La tentative de connexion a été lancée avant la fin du processus de jumelage | Terminez correctement le processus de jumelage par NIP; Exécutez de nouveau la demande de connexion |
| E\_SERVERTOOOLD | 0x8C114011 | La version du serveur est trop ancienne pour ce client. | La version de l'API côté client est plus récente que la version du point de terminaison sur l'appareil distant | Mettez à jour wdEndpoint sur l'ordinateur distant vers une version compatible |
| E\_ADMIN\_REQUIRED | 0x8C114016 | Privilèges d'administrateur requis. | Le point de terminaison ne s'exécute pas avec des privilèges élevés et l'opération requiert des autorisations de niveau administrateur | Exécutez de nouveau le point de terminaison en tant qu'administrateur |

## Remarques

`WdRemoteCopy` est un appel synchrone et bloquant. Il ne retourne pas tant que tous les fichiers n'ont pas été copiés, que l'opération n'a pas été annulée au moyen de [WdCancelRemoteCopy](/fr-CA/reference/remoting/functions/wdcancelremotecopy) ou qu'une erreur ne s'est pas produite.

Pour permettre l'annulation, créez un [WdCancellationHandle](/fr-CA/reference/remoting/structs/wdcancellationhandle) au moyen de [WdCreateCancellationHandle](/fr-CA/reference/remoting/functions/wdcreatecancellationhandle) avant d'appeler `WdRemoteCopy`, puis passez-le à [WdCancelRemoteCopy](/fr-CA/reference/remoting/functions/wdcancelremotecopy) à partir d'un thread distinct. Une fois que `WdRemoteCopy` a retourné, fermez le handle avec [WdCloseCancellationHandle](/fr-CA/reference/remoting/functions/wdclosecancellationhandle).

Utilisez [WdCopyDirection::CopyTo](/fr-CA/reference/remoting/enums/wdcopydirection) pour envoyer des fichiers du PC local vers l'appareil distant, ou `CopyFrom` pour récupérer des fichiers de l'appareil distant vers le PC local. La direction par défaut est `CopyTo`.

Le chemin distant est `destinationPath` pour `CopyTo` et `sourcePath` pour `CopyFrom`. Si ce chemin est absolu, le `commonRootAlias` de [WdCopyOptions](/fr-CA/reference/remoting/structs/wdcopyoptions) est ignoré. S'il est relatif, l'emplacement de racine commune par défaut est utilisé, sauf si un `commonRootAlias` est spécifié.

Pour recevoir des mises à jour de progression pendant la copie, fournissez une structure [WdCopyStatusCallbacks](/fr-CA/reference/remoting/structs/wdcopystatuscallbacks) contenant des pointeurs de fonctions de rappel.

<Warning>Un seul appel `WdRemoteCopy` peut être actif à la fois, quel que soit l'appareil cible ou le chemin de destination. Appeler `WdRemoteCopy` pendant qu'une autre copie est déjà en cours entraîne un comportement indéfini.  </Warning>
`WdRemoteCopy` ne réessaie pas automatiquement en cas d'échec. Si l'opération échoue en raison d'une interruption du réseau, l'appelant doit appeler de nouveau `WdRemoteCopy`. Les fichiers copiés avec succès avant l'échec demeurent à la destination; le comportement de copie delta garantit que seuls les fichiers incomplets ou manquants sont transférés de nouveau lors de la nouvelle tentative. Il n'y a aucun délai d'expiration; la copie se poursuit jusqu'à ce qu'elle soit terminée, qu'une erreur se produise ou qu'elle soit annulée.

## Exemples

### Exemple 1 : Copie de fichiers de base

Copie un dossier de build local vers un appareil distant en utilisant les paramètres par défaut. Tous les fichiers sont copiés sans filtrage, sans rapport de progression et sans prise en charge de l'annulation.

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

### Exemple 2 : Copie filtrée avec rapport de progression

Copie uniquement des types de fichiers précis tout en ignorant les artefacts de débogage et les répertoires intermédiaires. Un rappel de progression affiche l'état du transfert en direct dans la 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;
}
```

## Historique des modifications

| Version | Modification |
| - | - |
| [RIT 0.0.13-preview](/fr-CA/reference/remoting/release-versions#release-versions) | Implémentation de `CopyFrom`. Les versions antérieures retournent `E_NOTIMPL` pour cette direction, même si la valeur d'énumération est déclarée. |
| [RIT 0.0.8-Preview](/fr-CA/reference/remoting/release-versions#release-versions) | Introduction de `WdRemoteCopy` avec la prise en charge de `CopyTo`. |

## Configuration requise

| Exigence | Valeur |
| - | - |
| **En-tête** | WdRemoteIteration.h |
| **Bibliothèque** | wdremoteapi.lib |
| **Système d'exploitation pris en charge** | Windows 11 et versions ultérieures |
| **Architectures prises en charge** | x64, ARM64 |

## Voir aussi

* [WdCancelRemoteCopy](/fr-CA/reference/remoting/functions/wdcancelremotecopy)
* [WdCancellationHandle](/fr-CA/reference/remoting/structs/wdcancellationhandle)
* [WdCreateCancellationHandle](/fr-CA/reference/remoting/functions/wdcreatecancellationhandle)
* [WdCloseCancellationHandle](/fr-CA/reference/remoting/functions/wdclosecancellationhandle)
* [WdCopyOptions](/fr-CA/reference/remoting/structs/wdcopyoptions)
* [WdCopySearchOptions](/fr-CA/reference/remoting/structs/wdcopysearchoptions)
* [WdCopyStatusCallbacks](/fr-CA/reference/remoting/structs/wdcopystatuscallbacks)
* [WdCopyDirection](/fr-CA/reference/remoting/enums/wdcopydirection)
* [Codes d'erreur de l'API XBOX PC Remote Iteration](/fr-CA/reference/remoting/error-codes)
* [API XBOX PC Remote Iteration](/fr-CA/reference/remoting/remoteiteration_members)


## Related topics

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