NtCopyFileChunk 함수(ntifs.h)

아티클
02/07/2025

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

읽을 원본 파일의 HANDLE입니다.

[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 모든 읽기 및 쓰기 작업은 다음과 같습니다.

KernelMode IRP의 요청자 모드로 설정
IopCopyInformationType 형식의 IRP 확장입니다.

필터는 IRP 확장에 직접 액세스할 수 없지만 이 확장의 현재 상태를 확인하고 FltGetCopyInformationFromCallbackData호출하여 콜백 데이터에서 복사 정보를 가져올 수 있습니다.

복사 정보가 IRP 확장에 있으므로 빠른 IO를 이 복사본에서 사용할 수 없습니다(빠른 IO는 IRP를 만들지 않음).

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; 
    } 
}

자세한 내용은 커널 모드 파일 복사 및 복사 파일 시나리오 검색을 참조하세요.