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
読み取るソース ファイルの 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 には、ソース ファイルの読み取りと宛先ファイルへの書き込みの 2 つの I/O 操作が含まれています。 各 I/O は内部的に独自の完了を持ちますが、コピー操作が完了すると、呼び出し元のイベント (またはイベントが指定されていない場合は宛先ファイル ハンドル) が通知されます。
ソース ファイルとコピー先ファイルは、非同期的または同期的に開くことができます。 呼び出し元は 2 つのハンドル間で一貫していることをお勧めしますが、必須ではありません。 指定されたハンドルに応じて、 NtCopyFileChunk は次の表に示すように、コピー操作の異なるポイントでを返します。
| ソース ハンドル | 宛先ハンドル | 戻り値の条件 |
|---|---|---|
| 非同期 | 非同期 | 読み取りが正常にキューに登録されたら、または読み取りをキューに登録する前にエラーが発生した場合は 。 |
| 非同期 | Synchronous | 書き込みが完了したら、または書き込み完了前にエラーがある場合は 。 |
| 同期 | 同期 | 書き込みが完了したら、または書き込み完了前にエラーがある場合は 。 |
| Synchronous | 非同期 | 書き込みが正常にキューに登録されたら、または書き込みをキューに入る前にエラーがある場合は 。 |
STATUS_PENDINGが返された場合、呼び出された は操作の完了を待ってから、最終的な状態の I/O 状態ブロックを確認する必要があります。 STATUS_SUCCESSが返された場合、または I/O 状態ブロックが成功を示している場合、呼び出し元は IoStatusBlock を調べて、コピーされたバイト数を確認する必要があります。
キャッシュされていない I/O に対していずれかのファイルを開く場合、呼び出し元は、要求された長さが、キャッシュされていないファイルとして開かれているファイルとセクターアラインされていることを確認する必要があります。 両方の場合、長さは 2 つのより大きなセクター サイズに合わせる必要があります。
NtCopyFileChunk のすべての読み取り操作と書き込み操作には、次の機能があります。
- IRP のリクエスタ モードが KernelMode に設定されている
- 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;
}
}
詳細については、 カーネル モードのファイル コピーとコピー ファイルの検出のシナリオに関する ページを参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 11 バージョン 22H2 |
| Header | ntifs.h |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |