Fonction NtCopyFileChunk (ntifs.h)

Article
02/07/2025

La routine NtCopyFileChunk copie les données du fichier source dans le fichier de destination.

Syntaxe

__kernel_entry NTSYSCALLAPI NTSTATUS NtCopyFileChunk(
  [in]           HANDLE           SourceHandle,
  [in]           HANDLE           DestHandle,
  [in, optional] HANDLE           Event,
  [out]          PIO_STATUS_BLOCK IoStatusBlock,
  [in]           ULONG            Length,
  [in]           PLARGE_INTEGER   SourceOffset,
  [in]           PLARGE_INTEGER   DestOffset,
  [in, optional] PULONG           SourceKey,
  [in, optional] PULONG           DestKey,
  [in]           ULONG            Flags
);

Paramètres

[in] SourceHandle

HANDLE du fichier source à lire.

[in] DestHandle

HANDLE du fichier de destination. Les données de fichierSourceHandle sont copiées dans fichier destHandle. Les ports d’achèvement peuvent être utilisés sur ce handle.

[in, optional] Event

Événement facultatif à signaler lorsque l’opération de copie est terminée.

[out] IoStatusBlock

Pointeur vers une structure IO_STATUS_BLOCK qui reçoit l’état d’achèvement final et d’autres informations sur l’opération de copie.

[in] Length

Longueur des données à copier, en octets.

[in] SourceOffset

Décalage d’octets de départ dans le fichier source pour commencer l’opération de lecture.

[in] DestOffset

Décalage d’octets de départ dans le fichier de destination pour commencer l’opération d’écriture.

[in, optional] SourceKey

Clé facultative à utiliser s’il existe des oplocks associés au fichier source.

[in, optional] DestKey

Clé facultative à utiliser s’il existe des oplocks associés au fichier de destination.

[in] Flags

Indicateurs facultatifs. Actuellement, il n’existe aucune valeur d’indicateur valide.

Valeur de retour

NtCopyFileChunk retourne STATUS_SUCCESS si la copie est correctement terminée, ou un code NTSTATUS tel que l’un des éléments suivants :

Code	Signification
STATUS_PENDING	La copie est en cours. Les appelants doivent attendre l’événement ou l’objet de fichier pour obtenir l’état final.
STATUS_[ERROR]	Diverses erreurs peuvent se produire comme NtReadFile et NtWriteFile .

Une fois l’écriture terminée, l’état de l’opération peut être déterminé en examinant le champ état de IoStatusBlock.

Consultez Remarques pour plus d’informations sur la gestion des E/S synchrones/asynchrones.

Remarques

NtCopyFileChunk copie les données d’un fichier source dans un fichier de destination à l’aide des décalages de fichiers fournis pour la longueur demandée. Si la longueur dépasse la fin du fichier (EOF) sur le fichier source, NtCopyFileChunk lit et copie uniquement les données vers la destination jusqu’à l’EOF de la source. Les appelants peuvent obtenir le nombre réel d’octets écrits à partir du IoStatusBlock.

NtCopyFileChunk inclut deux opérations d’E/S : une lecture du fichier source et une écriture dans le fichier de destination. Bien que chaque E/S ait sa propre saisie semi-automatique, l’événement de l’appelant (ou le handle de fichier de destination si aucun événement n’est fourni) est signalé lorsque l’opération de copie est terminée.

Les fichiers source et de destination peuvent être ouverts de manière asynchrone ou synchrone. Bien qu’il soit recommandé que les appelants soient cohérents entre les deux handles, il n’est pas nécessaire. Selon les handles fournis, NtCopyFileChunk retourne à différents points de l’opération de copie, comme spécifié dans le tableau suivant.

Source Handle	Destination Handle	Conditions de retour
Asynchrone	Asynchrone	Une fois que la lecture a été correctement mise en file d’attente OU s’il existe des erreurs avant de mettre en file d’attente la lecture.
Asynchrone	Synchrone	Une fois l’écriture terminée ou s’il y a des erreurs avant la fin de l’écriture.
Synchrone	Synchrone	Une fois l’écriture terminée ou s’il y a des erreurs avant la fin de l’écriture.
Synchrone	Asynchrone	Une fois que l’écriture a été correctement mise en file d’attente OU s’il existe des erreurs avant de mettre en file d’attente l’écriture.

Si STATUS_PENDING est retourné, l’appel doit attendre la fin de l’opération avant d’examiner le bloc d’état d’E/S pour l’état final. Si STATUS_SUCCESS est retourné ou si le bloc d’état d’E/S indique la réussite, l’appelant doit examiner l'IoStatusBlock pour déterminer le nombre d’octets copiés.

Si l’un ou l’autre fichier est ouvert pour les E/S non mises en cache, l’appelant doit s’assurer que la longueur demandée est alignée sur le secteur, selon le fichier ouvert comme non mis en cache. Si les deux, la longueur doit être alignée sur la plus grande taille du secteur des deux.

Toutes les opérations de lecture et d’écriture de NtCopyFileChunk auront :

Le mode demandeur de l’IRP défini sur KernelMode
Extension IRP de type IopCopyInformationType.

Les filtres n’ont pas accès directement aux extensions IRP, mais peuvent vérifier la présence de cette extension et obtenir des informations de copie à partir des données de rappel en appelant FltGetCopyInformationFromCallbackData.

Les E/S rapides ne sont pas disponibles dans cette copie, car les informations de copie sont présentes dans l’extension IRP (et les E/S rapides ne créent pas d’IRPs).

NtCopyFileChunk est utilisé en interne par CopyFile pour la plupart des formes de copie. Les exceptions actuelles incluent les copies cloud, le déchargement SMB et ODX.

L’exemple suivant montre comment utiliser NtCopyFileChunk.


// Input parameters to NtCopyFileChunk. Opening
// the file handles is done using NtCreateFile
// and creating the event is done with CreateEvent.
// This is not shown in this code sample. 

HANDLE sourceHandle; 
HANDLE destHandle; 
HANDLE event; 
IO_STATUS_BLOCK ioStatusBlock; 
ULONG length; 
LARGE_INTEGER sourceOffset; 
LARGE_INTEGER destOffset; 

// Copy the data 

status = NtCopyFileChunk( sourceHandle, 
                          destHandle, 
                          event, 
                          &ioStatusBlock, 
                          length, 
                          &sourceOffset, 
                          &destOffset, 
                          NULL, 
                          NULL, 
                          0 ); 

// Wait for the copy to complete 

if (status == STATUS_PENDING) { 
    status = NtWaitForSingleObject( event, FALSE, NULL ); 

    if (NT_SUCCESS(status)) { 
        status = ioStatusBlock.Status; 
    } 
}

Pour plus d’informations, consultez copie de fichiers en mode noyau et détection des scénarios de copie de fichier.