NtCopyFileChunk 함수(ntifs.h)
NtCopyFileChunk 루틴은 원본 파일의 데이터를 대상 파일로 복사합니다.
구문
__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
);
매개 변수
[in] SourceHandle
읽을 원본 파일의 핸들입니다.
[in] DestHandle
대상 파일의 HANDLE입니다. SourceHandle 파일의 데이터는 DestHandle의 파일에 복사됩니다. 완료 포트는 이 핸들에서 사용할 수 있습니다.
[in, optional] Event
복사 작업이 완료될 때 신호를 받을 선택적 이벤트입니다.
[out] IoStatusBlock
최종 완성 상태 수신하는 IO_STATUS_BLOCK 구조체에 대한 포인터 및 복사 작업에 대한 기타 정보입니다.
[in] Length
복사할 데이터의 길이(바이트)입니다.
[in] SourceOffset
읽기 작업을 시작할 원본 파일 내의 시작 바이트 오프셋입니다.
[in] DestOffset
쓰기 작업을 시작할 대상 파일 내의 시작 바이트 오프셋입니다.
[in, optional] SourceKey
원본 파일과 연결된 oplock이 있는 경우 사용할 선택적 키입니다.
[in, optional] DestKey
대상 파일과 연결된 oplock이 있는 경우 사용할 선택적 키입니다.
[in] Flags
선택적 플래그입니다. 현재 유효한 플래그 값이 없습니다.
반환 값
NtCopyFileChunk 는 복사본이 성공적으로 완료된 경우 STATUS_SUCCESS 반환하거나 다음 중 하나와 같은 NTSTATUS 코드를 반환합니다.
| 코드 | 의미 |
|---|---|
| STATUS_PENDING | 복사본이 진행 중입니다. 호출자는 이벤트 또는 파일 개체에서 대기하여 최종 상태 가져와야 합니다. |
| STATUS_[ERROR] | NtReadFile 및 NtWriteFile과 유사한 다양한 오류가 발생할 수 있습니다. |
쓰기가 완료되면 IoStatusBlock의 상태 필드를 검사하여 작업의 상태 확인할 수 있습니다.
동기/비동기 I/O 처리에 대한 자세한 내용은 설명을 참조하세요.
설명
NtCopyFileChunk 는 요청된 길이에 대해 제공된 파일 오프셋을 사용하여 원본 파일에서 대상 파일로 데이터를 복사합니다. 길이가 원본 파일의 EOF(파일 끝)를 초과하는 경우 NtCopyFileChunk 는 원본의 EOF까지만 데이터를 읽고 대상에 복사합니다. 호출자는 IoStatusBlock에서 작성된 실제 바이트 수를 가져올 수 있습니다.
NtCopyFileChunk 에는 원본 파일 읽기 및 대상 파일에 대한 쓰기라는 두 가지 I/O 작업이 포함됩니다. 각 I/O는 내부적으로 자체 완료되지만 복사 작업이 완료되면 호출자의 이벤트(또는 이벤트가 제공되지 않은 경우 대상 파일 핸들)가 신호를 보냅니다.
원본 및 대상 파일을 비동기적으로 또는 동기적으로 열 수 있습니다. 호출자는 두 핸들 간에 일관성을 유지하는 것이 좋지만 필수는 아닙니다. 제공된 핸들에 따라 NtCopyFileChunk 는 다음 표에 지정된 대로 복사 작업의 다른 지점에서 반환됩니다.
| 원본 핸들 | 대상 핸들 | 반환 조건 |
|---|---|---|
| 비동기 | 비동기 | 읽기가 성공적으로 큐에 대기되었거나 읽기를 큐에 대기하기 전에 오류가 있는 경우 입니다. |
| 비동기 | 동기 | 쓰기가 완료되면 또는 쓰기 완료 전에 오류가 있는 경우 입니다. |
| 동기 | 동기 | 쓰기가 완료되면 또는 쓰기 완료 전에 오류가 있는 경우 입니다. |
| 동기 | 비동기 | 쓰기가 성공적으로 큐에 대기되면 또는 쓰기를 큐에 대기하기 전에 오류가 있는 경우 입니다. |
STATUS_PENDING 반환되는 경우 호출된 는 최종 상태 대한 I/O 상태 블록을 보기 전에 작업이 완료되기를 기다려야 합니다. STATUS_SUCCESS 반환되거나 I/O 상태 블록이 성공을 나타내는 경우 호출자는 IoStatusBlock을 확인하여 복사된 바이트 수를 확인해야 합니다.
캐시되지 않은 I/O에 대해 두 파일이 모두 열려 있는 경우 호출자는 요청된 길이가 캐시되지 않은 파일로 열려 있는 파일과 섹터 정렬되었는지 확인해야 합니다. 둘 다인 경우 길이는 두 섹터의 더 큰 섹터 크기에 맞춰야 합니다.
NtCopyFileChunk의 모든 읽기 및 쓰기 작업에는 다음이 포함됩니다.
- IRP의 요청자 모드가 KernelMode로 설정
- IopCopyInformationType 형식의 IRP 확장입니다.
필터는 IRP 확장에 직접 액세스할 수 없지만 이 확장의 존재를 검사 FltGetCopyInformationFromCallbackData를 호출하여 콜백 데이터에서 복사 정보를 가져올 수 있습니다.
복사 정보가 IRP 확장에 있고 빠른 IO가 IRP를 만들지 않으므로 이 복사본에서는 빠른 IO를 사용할 수 없습니다.
NtCopyFileChunk 는 대부분의 복사본 형식에 대해 CopyFile 에서 내부적으로 사용됩니다. 현재 예외에는 클라우드 복사본, SMB 오프로드 및 ODX가 포함됩니다.
다음 예제에서는 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;
}
}
자세한 내용은 커널 모드 파일 복사 및 복사 파일 시나리오 검색 을 참조하세요.
요구 사항
| 요구 사항 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows 11, 버전 22H2 |
| 머리글 | ntifs.h |
| 라이브러리 | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |