Fonction NtCopyFileChunk (ntifs.h)

Article
02/26/2024

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 du fichier sourceHandle sont copiées dans le fichier de 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 de IO_STATUS_BLOCK qui reçoit le status 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’octet de début dans le fichier source pour commencer l’opération de lecture.

[in] DestOffset

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

[in, optional] SourceKey

Clé facultative à utiliser si des oplocks sont associés au fichier source.

[in, optional] DestKey

Clé facultative à utiliser si des oplocks sont associés au fichier de destination.

[in] Flags

Indicateurs facultatifs. Il n’existe actuellement aucune valeur d’indicateur valide.

Valeur retournée

NtCopyFileChunk retourne STATUS_SUCCESS si la copie est 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 la status finale.
STATUS_[ERREUR]	Différentes erreurs peuvent se produire comme NtReadFile et NtWriteFile.

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

Pour plus d’informations sur la gestion des E/S synchrones/ asynchrones, consultez Remarques .

Remarques

NtCopyFileChunk copie les données d’un fichier source dans un fichier de destination à l’aide des décalages de fichier 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 dans la destination jusqu’à l’EOF de la source. Les appelants peuvent obtenir le nombre réel d’octets écrits à partir de l’IoStatusBlock.

NtCopyFileChunk comprend 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 complétion en interne, 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, cela n’est pas obligatoire. En fonction des 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 y a des erreurs avant la mise en file d’attente de 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 y a des erreurs avant la mise en file d’attente de l’écriture.

Si STATUS_PENDING est retourné, l’appelé doit attendre que l’opération se termine avant d’examiner le bloc d’E/S status pour la status finale. Si STATUS_SUCCESS est retourné ou si le bloc d’E/S status indique la réussite, l’appelant doit examiner ioStatusBlock pour déterminer le nombre d’octets copiés.

Si l’un des fichiers 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 avec le fichier ouvert comme non mis en cache. Si les deux, la longueur doit être alignée sur la plus grande taille de secteur des deux.

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

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 case activée 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 Fast IO ne crée 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 fichier de copie .