Fungsi NtCopyFileChunk (ntifs.h)

Artikel
01/13/2024

NtCopyFileChunk rutin menyalin data dari file sumber ke dalam file tujuan.

Sintaks

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

Parameter

[in] SourceHandle

HANDLE file sumber yang akan dibaca.

[in] DestHandle

HANDLE file tujuan. Data dari file SourceHandle disalin ke dalam file DestHandle. Port penyelesaian dapat digunakan pada handel ini.

[in, optional] Event

Peristiwa opsional yang akan disinyalkan ketika operasi salin selesai.

[out] IoStatusBlock

Penunjuk ke struktur IO_STATUS_BLOCK yang menerima status penyelesaian akhir dan informasi lain tentang operasi penyalinan.

[in] Length

Panjang data yang akan disalin, dalam byte.

[in] SourceOffset

Offset byte awal dalam file sumber untuk memulai operasi baca.

[in] DestOffset

Offset byte awal dalam file tujuan untuk memulai operasi tulis.

[in, optional] SourceKey

Kunci opsional yang akan digunakan jika ada oplock yang terkait dengan file sumber.

[in, optional] DestKey

Kunci opsional yang akan digunakan jika ada oplock yang terkait dengan file tujuan.

[in] Flags

Bendera opsional. Saat ini tidak ada nilai bendera yang valid.

Mengembalikan nilai

NtCopyFileChunk mengembalikan STATUS_SUCCESS jika salinan berhasil diselesaikan, atau kode NTSTATUS seperti salah satu hal berikut:

Kode	Makna
STATUS_PENDING	Salinan sedang berlangsung. Penelepon harus menunggu pada peristiwa atau objek file untuk mendapatkan status akhir.
STATUS_[ERROR]	Berbagai kesalahan dapat terjadi mirip dengan NtReadFile dan NtWriteFile.

Setelah penulisan menyelesaikan status operasi dapat ditentukan dengan memeriksa bidang StatusIoStatusBlock.

Lihat Keterangan untuk detail tentang penanganan I/O sinkron/asinkron.

Keterangan

NtCopyFileChunk menyalin data dari file sumber ke file tujuan menggunakan offset file yang disediakan untuk panjang yang diminta. Jika panjangnya melampaui akhir file (EOF) pada file sumber, maka NtCopyFileChunk hanya akan membaca dan menyalin data ke tujuan hingga EOF sumber. Penelepon bisa mendapatkan jumlah byte aktual yang ditulis dari IoStatusBlock.

NtCopyFileChunk mencakup dua operasi I/O: baca file sumber dan tulis ke file tujuan. Meskipun setiap I/O secara internal memiliki penyelesaiannya sendiri, peristiwa pemanggil (atau handel file tujuan jika tidak ada peristiwa yang disediakan) akan diberi sinyal ketika operasi salin selesai.

File sumber dan tujuan dapat dibuka secara asinkron atau sinkron. Meskipun disarankan agar penelepon konsisten di antara dua handel, itu tidak diperlukan. Bergantung pada handel yang disediakan, NtCopyFileChunk akan kembali pada titik yang berbeda dalam operasi salin seperti yang ditentukan dalam tabel berikut.

Handel Sumber	Handel Tujuan	Kondisi Pengembalian
Asinkron	Asinkron	Setelah pembacaan berhasil diantrekan ATAU jika ada kesalahan sebelum mengantre baca.
Asinkron	Sinkron	Setelah penulisan selesai ATAU jika ada kesalahan sebelum penyelesaian penulisan.
Sinkron	Sinkron	Setelah penulisan selesai ATAU jika ada kesalahan sebelum penyelesaian penulisan.
Sinkron	Asinkron	Setelah penulisan berhasil diantrekan ATAU jika ada kesalahan sebelum mengantre tulis.

Jika STATUS_PENDING dikembalikan, panggilan harus menunggu operasi selesai sebelum melihat blok status I/O untuk status akhir. Jika STATUS_SUCCESS dikembalikan atau blok status I/O menunjukkan keberhasilan, pemanggil harus melihat IoStatusBlock untuk menentukan berapa banyak byte yang disalin.

Jika salah satu file dibuka untuk I/O yang tidak di-cache, pemanggil harus memastikan bahwa panjang yang diminta selaras dengan file mana pun yang dibuka sebagai tidak di-cache. Jika keduanya, panjangnya harus selaras dengan ukuran sektor yang lebih besar dari keduanya.

Semua operasi baca dan tulis dari NtCopyFileChunk akan memiliki:

Mode pemohon IRP diatur ke KernelMode
Ekstensi IRP jenis IopCopyInformationType.

Filter tidak memiliki akses ke ekstensi IRP secara langsung tetapi dapat memeriksa keberadaan ekstensi ini dan mendapatkan informasi penyalinan dari data panggilan balik dengan memanggil FltGetCopyInformationFromCallbackData.

IO cepat tidak tersedia dalam salinan ini karena informasi salin ada di ekstensi IRP (dan Fast IO tidak membuat RUNP).

NtCopyFileChunk digunakan secara internal oleh CopyFile untuk sebagian besar bentuk salinan. Pengecualian saat ini termasuk salinan cloud, offload SMB, dan ODX.

Contoh berikut menunjukkan cara menggunakan 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; 
    } 
}

Lihat Penyalinan file mode kernel dan mendeteksi skenario salin file untuk informasi selengkapnya.