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 コードを返します。

書き込みが完了したら、IoStatusBlock の [状態] フィールドを調べることで、操作の状態を確認できます。

同期/非同期 I/O の処理の詳細については、「 解説 」を参照してください。

注釈

NtCopyFileChunk は、要求された長さの指定されたファイル オフセットを使用して、ソース ファイルからコピー先ファイルにデータをコピーします。 長さがソース ファイルのファイルの末尾 (EOF) を超える場合、 NtCopyFileChunk は、ソースの EOF までのデータの読み取りとコピーのみを行います。 呼び出し元は、 IoStatusBlock から書き込まれた実際のバイト数を取得できます。

NtCopyFileChunk には、ソース ファイルの読み取りと宛先ファイルへの書き込みの 2 つの I/O 操作が含まれています。 各 I/O は内部的に独自の完了を持ちますが、コピー操作が完了すると、呼び出し元のイベント (またはイベントが指定されていない場合は宛先ファイル ハンドル) が通知されます。

ソース ファイルとコピー先ファイルは、非同期的または同期的に開くことができます。 呼び出し元は 2 つのハンドル間で一貫していることをお勧めしますが、必須ではありません。 指定されたハンドルに応じて、 NtCopyFileChunk は次の表に示すように、コピー操作の異なるポイントでを返します。

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

詳細については、 カーネル モードのファイル コピーとコピー ファイルの検出のシナリオに関する ページを参照してください。

要件

こちらもご覧ください

FltGetCopyInformationFromCallbackData

IO_STATUS_BLOCK

NtCreateFile