code de contrôle IOCTL_COPYCHUNK

Le code de contrôle IOCTL_COPYCHUNK lance une copie côté serveur d’une plage de données, également appelée segment.

Pour effectuer cette opération, appelez la fonction DeviceIoControl avec les paramètres suivants.

BOOL DeviceIoControl(
  (HANDLE) hDevice,             // handle to device
  IOCTL_COPYCHUNK,              // dwIoControlCode
  (LPVOID) lpInBuffer,          // input buffer
  (DWORD) nInBufferSize,        // size of input buffer
  (LPVOID) lpOutBuffer,         // output buffer
  (DWORD) nOutBufferSize,       // size of output buffer
  (LPDWORD) lpBytesReturned,    // number of bytes returned
  (LPOVERLAPPED) lpOverlapped   // OVERLAPPED structure
);

Paramètres

hDevice [in]

Handle du fichier qui est la cible de l’opération de copie côté serveur. Pour obtenir ce handle, appelez la fonction CreateFile .

dwIoControlCode [in]

Code de contrôle de l’opération. Utilisez IOCTL_COPYCHUNK pour cette opération.

lpInBuffer

Pointeur vers la mémoire tampon d’entrée, structure SRV_COPYCHUNK_COPY . Pour plus d'informations, consultez la section Notes.

nInBufferSize [in]

Taille de la mémoire tampon d’entrée, en octets.

lpOutBuffer [out]

Pointeur vers la mémoire tampon de sortie, structure SRV_COPYCHUNK_RESPONSE . Pour plus d'informations, consultez la section Notes.

nOutBufferSize [in]

Taille de la mémoire tampon de sortie en octets.

lpBytesReturned [out]

Pointeur vers une variable qui reçoit la taille des données stockées dans la mémoire tampon de sortie, en octets.

Si la mémoire tampon de sortie est trop petite, l’appel échoue, la fonction GetLastError retourne ERROR_INSUFFICIENT_BUFFER et lpBytesReturned est égal à zéro.

Si le paramètre lpOverlapped a la valeur NULL, lpBytesReturned ne peut pas être NULL. Même lorsqu’une opération ne retourne aucune donnée de sortie et que le paramètre lpOutBuffer est NULL, DeviceIoControl utilise lpBytesReturned. Après une telle opération, la valeur de lpBytesReturned est sans signification.

Si lpOverlapped n’est pas NULL, lpBytesReturned peut être NULL. Si lpOverlapped n’est pas NULL et que l’opération retourne des données, lpBytesReturned est sans signification tant que l’opération qui se chevauche n’est pas terminée. Pour récupérer le nombre d’octets retournés, appelez la fonction GetOverlappedResult . Si le paramètre hDevice est associé à un port d’achèvement d’E/S, vous pouvez récupérer le nombre d’octets retournés en appelant la fonction GetQueuedCompletionStatus .

lpOverlapped [in]

Pointeur vers une structure QUI SE CHEVAUCHE .

Si le paramètre hDevice a été ouvert sans spécifier FILE_FLAG_OVERLAPPED, lpOverlapped est ignoré.

Si hDevice a été ouvert avec l’indicateur FILE_FLAG_OVERLAPPED , l’opération est effectuée en tant qu’opération superposée (asynchrone). Dans ce cas, lpOverlapped doit pointer vers une structure OVERLAPPED valide qui contient un handle vers un objet d’événement. Sinon, la fonction échoue de manière imprévisible.

Pour les opérations qui se chevauchent, DeviceIoControl retourne immédiatement et l’objet d’événement est signalé une fois l’opération terminée. Sinon, la fonction ne retourne pas tant que l’opération n’est pas terminée ou tant qu’une erreur se produit.

Valeur retournée

Si l’opération se termine correctement, DeviceIoControl retourne une valeur différente de zéro.

Si l’opération échoue ou est en attente, DeviceIoControl retourne zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Ce code de contrôle n’a pas de fichier d’en-tête associé. Vous devez définir le code de contrôle et les structures de données comme suit.

#define IOCTL_COPYCHUNK CTL_CODE(FILE_DEVICE_NETWORK_FILE_SYSTEM, 262, METHOD_BUFFERED,  FILE_READ_ACCESS)

typedef struct _SRV_COPYCHUNK {
    LARGE_INTEGER SourceOffset;
    LARGE_INTEGER DestinationOffset;
    ULONG  Length;
} SRV_COPYCHUNK, *PSRV_COPYCHUNK;

typedef struct _SRV_COPYCHUNK_COPY {
    SRV_RESUME_KEY SourceFile;
    ULONG          ChunkCount;
    ULONG          Reserved;
    SRV_COPYCHUNK  Chunk[1];    // Array
} SRV_COPYCHUNK_COPY, *PSRV_COPYCHUNK_COPY;

typedef struct _SRV_COPYCHUNK_RESPONSE {
    ULONG          ChunksWritten;
    ULONG          ChunkBytesWritten;
    ULONG          TotalBytesWritten;
} SRV_COPYCHUNK_RESPONSE, *PSRV_COPYCHUNK_RESPONSE;

Ces membres peuvent être décrits comme suit.

Membre	Description
SourceOffset	Décalage, en octets, du début du fichier source au bloc à copier.
DestinationOffset	Décalage, en octets, du début du fichier cible à l’emplacement où le bloc doit être copié.
Longueur	Nombre d’octets de données dans le bloc à copier. Doit être supérieur à zéro et inférieur ou égal à 1 Mo. Longueur * ChunkCount doit être inférieur ou égal à 16 Mo.
SourceFile	Clé qui représente le fichier source avec les données à copier. Cette clé est obtenue via FSCTL_SRV_REQUEST_RESUME_KEY.
ChunkCount	Nombre de blocs à copier. Doit être supérieur à zéro et inférieur ou égal à 256.
Réservés au	Ce membre est réservé à l’utilisation du système ; n’utilisez pas.
Morceau	Tableau de structures ChunkCountSRV_COPYCHUNK, une pour chaque bloc à copier. La longueur, en octets, de ce tableau doit être ChunkCount * sizeof(SRV_COPYCHUNK).
ChunksWritten	Si l’opération a échoué avec ERROR_INVALID_PARAMETER, cette valeur indique le nombre maximal de blocs acceptés par le serveur dans une seule requête, soit 256. Sinon, cette valeur indique le nombre de blocs qui ont été correctement écrits.
ChunkBytesWritten	Si l’opération a échoué avec ERROR_INVALID_PARAMETER, cette valeur indique le nombre maximal d’octets que le serveur autorise à écrire en un seul bloc, soit 1 Mo. Sinon, cette valeur indique le nombre d’octets qui ont été correctement écrits dans le dernier bloc qui n’a pas été traité correctement (si une écriture partielle s’est produite).
TotalBytesWritten	Si l’opération a échoué avec ERROR_INVALID_PARAMETER, cette valeur indique le nombre maximal d’octets que le serveur copie dans une seule requête, soit 16 Mo. Sinon, cette valeur indique le nombre d’octets qui ont été correctement écrits.

 

Voir aussi

DeviceIoControl

FSCTL_SRV_REQUEST_RESUME_KEY