> ## 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/reference/remoting/release-versions#release-versions).

**`CopyFrom` pris en charge à partir de :** [RIT 0.0.13-preview](/fr/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\***

Nom d'hôte ou adresse IP de l'appareil distant (par exemple, `"192.168.1.100"` ou `"MyDevKit"`).

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

Chemin source à partir duquel copier (par exemple, `"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\***

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

`_In_opt_ copyOptions`\
Type : **const [WdCopyOptions](/fr/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/reference/remoting/structs/wdcopysearchoptions)\***

Facultatif. Spécifie des modèles d'inclusion/exclusion de fichiers et des filtres d'attributs (par exemple, `"*.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/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/reference/remoting/structs/wdcancellationhandle)**

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

### Valeur de retour

Type : **HRESULT**

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

#### Codes d'erreur

| Code | Valeur | Description | Cause racine | Résolution des problèmes |
| - | - | - | - | - |
| 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 rapport 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 de pare-feu et la disponibilité du service sur l'ordinateur distant ; Vérifiez la visibilité entre les appareils, qui doivent pouvoir s'envoyer des pings ; Réessayez 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 via DNS ou 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 (par exemple, format IP incorrect, IP erronée ou protocole non pris en charge). | Confirmez que l'adresse IP est correcte ; 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 démarré avant la fin du processus d'appairage | Terminez correctement le processus d'appairage par code PIN ; Exécutez à 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 démarré avant la fin du processus d'appairage | Terminez correctement le processus d'appairage par code PIN ; Exécutez à 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 nécessite des autorisations de niveau Administrateur | Réexécutez 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 via [WdCancelRemoteCopy](/fr/reference/remoting/functions/wdcancelremotecopy) ou qu'une erreur ne s'est pas produite.

Pour activer l'annulation, créez un [WdCancellationHandle](/fr/reference/remoting/structs/wdcancellationhandle) à l'aide de [WdCreateCancellationHandle](/fr/reference/remoting/functions/wdcreatecancellationhandle) avant d'appeler `WdRemoteCopy`, puis passez-le à [WdCancelRemoteCopy](/fr/reference/remoting/functions/wdcancelremotecopy) depuis un thread distinct. Après le retour de `WdRemoteCopy`, fermez le handle avec [WdCloseCancellationHandle](/fr/reference/remoting/functions/wdclosecancellationhandle).

Utilisez [WdCopyDirection::CopyTo](/fr/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/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/reference/remoting/structs/wdcopystatuscallbacks) contenant des pointeurs de fonctions de rappel.

<Warning>Un seul appel à `WdRemoteCopy` peut être actif à la fois, quels que soient l'appareil cible ou le chemin de destination. Appeler `WdRemoteCopy` alors qu'une autre copie est déjà en cours entraîne un comportement non défini.  </Warning>
`WdRemoteCopy` ne réessaie pas automatiquement en cas d'échec. Si l'opération échoue en raison d'une interruption réseau, l'appelant doit appeler à nouveau `WdRemoteCopy`. Les fichiers copiés avec succès avant l'échec restent sur la destination ; le comportement de copie delta garantit que seuls les fichiers incomplets ou manquants sont retransférés lors d'une nouvelle tentative. Il n'y a pas de 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 à l'aide des paramètres par défaut. Tous les fichiers sont copiés sans filtrage, sans rapport de progression ni 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 spécifiques 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/reference/remoting/release-versions#release-versions) | Implémentation de `CopyFrom`. Les versions antérieures renvoient `E_NOTIMPL` pour cette direction, même si la valeur d'énumération est déclarée. |
| [RIT 0.0.8-Preview](/fr/reference/remoting/release-versions#release-versions) | Introduction de `WdRemoteCopy` avec 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/reference/remoting/functions/wdcancelremotecopy)
* [WdCancellationHandle](/fr/reference/remoting/structs/wdcancellationhandle)
* [WdCreateCancellationHandle](/fr/reference/remoting/functions/wdcreatecancellationhandle)
* [WdCloseCancellationHandle](/fr/reference/remoting/functions/wdclosecancellationhandle)
* [WdCopyOptions](/fr/reference/remoting/structs/wdcopyoptions)
* [WdCopySearchOptions](/fr/reference/remoting/structs/wdcopysearchoptions)
* [WdCopyStatusCallbacks](/fr/reference/remoting/structs/wdcopystatuscallbacks)
* [WdCopyDirection](/fr/reference/remoting/enums/wdcopydirection)
* [Codes d'erreur de l'API XBOX PC Remote Iteration](/fr/reference/remoting/error-codes)
* [API XBOX PC Remote Iteration](/fr/reference/remoting/remoteiteration_members)


## Related topics

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