コントロール コードのIOCTL_COPYCHUNK

IOCTL_COPYCHUNKコントロール コードは、チャンクとも呼ばれる、データ範囲のサーバー側コピーを開始します。

この操作を実行するには、次のパラメーターを使用して DeviceIoControl 関数を呼び出します。

BOOL DeviceIoControl(
  (HANDLE) hDevice,             // handle to device
  IOCTL_COPYCHUNK,              // dwIoControlCode
  (LPVOID) lpInBuffer,          // input buffer
  (DWORD) nInBufferSize,        // size of input buffer
  (LPVOID) lpOutBuffer,         // output buffer
  (DWORD) nOutBufferSize,       // size of output buffer
  (LPDWORD) lpBytesReturned,    // number of bytes returned
  (LPOVERLAPPED) lpOverlapped   // OVERLAPPED structure
);

パラメーター

hDevice [in]

サーバー側のコピー操作のターゲットであるファイルへのハンドル。 このハンドルを取得するには、 CreateFile 関数を呼び出します。

dwIoControlCode [in]

操作の制御コード。 この操作 にはIOCTL_COPYCHUNK を使用します。

lpInBuffer

入力バッファーへのポインター。 SRV_COPYCHUNK_COPY 構造体。 詳細については、「解説」を参照してください。

nInBufferSize [in]

入力バッファーのサイズ (バイト単位)。

lpOutBuffer [out]

出力バッファーへのポインター。 SRV_COPYCHUNK_RESPONSE 構造体。 詳細については、「解説」を参照してください。

nOutBufferSize [in]

出力バッファーのサイズ (バイト単位)。

lpBytesReturned [out]

出力バッファーに格納されているデータのサイズをバイト単位で受け取る変数へのポインター。

出力バッファーが小さすぎる場合、呼び出しは失敗し、 GetLastError 関数は ERROR_INSUFFICIENT_BUFFERを返し、 lpBytesReturned は 0 です。

lpOverlapped パラメーターが NULL の場合、lpBytesReturned を NULL にすることはできません。 操作が出力データを返せず、 lpOutBuffer パラメーターが NULL の場合でも、 DeviceIoControl は lpBytesReturned を使用します。 このような操作の後、 lpBytesReturned の値は意味がありません。

lpOverlapped が NULL でない場合、lpBytesReturned は NULL にすることができます。 lpOverlapped が NULL ではなく、操作がデータを返す場合、重複する操作が完了するまで lpBytesReturned は意味がありません。 返されたバイト数を取得するには、 GetOverlappedResult 関数を呼び出します。 hDevice パラメーターが I/O 入力候補ポートに関連付けられている場合は、GetQueuedCompletionStatus 関数を呼び出して返されるバイト数を取得できます。

lpOverlapped [in]

OVERLAPPED 構造体へのポインター。

FILE_FLAG_OVERLAPPEDを指定せずに hDevice パラメーターを開いた場合、lpOverlapped は無視されます。

hDevice が FILE_FLAG_OVERLAPPED フラグで開かれた場合、操作は重複する (非同期) 操作として実行されます。 この場合、 lpOverlapped は、イベント オブジェクトへのハンドルを含む有効な OVERLAPPED 構造体を指す必要があります。 それ以外の場合、関数は予測できない方法で失敗します。

重複する操作の場合、 DeviceIoControl はすぐに返され、操作が完了するとイベント オブジェクトが通知されます。 それ以外の場合、操作が完了するまで、またはエラーが発生するまで、関数は戻りません。

戻り値

操作が正常に完了すると、 DeviceIoControl は 0 以外の値を返します。

操作が失敗した場合、または保留中の場合、 DeviceIoControl は 0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

注釈

このコントロール コードには、関連付けられたヘッダー ファイルがありません。 制御コードとデータ構造は、次のように定義する必要があります。

#define IOCTL_COPYCHUNK CTL_CODE(FILE_DEVICE_NETWORK_FILE_SYSTEM, 262, METHOD_BUFFERED,  FILE_READ_ACCESS)

typedef struct _SRV_COPYCHUNK {
    LARGE_INTEGER SourceOffset;
    LARGE_INTEGER DestinationOffset;
    ULONG  Length;
} SRV_COPYCHUNK, *PSRV_COPYCHUNK;

typedef struct _SRV_COPYCHUNK_COPY {
    SRV_RESUME_KEY SourceFile;
    ULONG          ChunkCount;
    ULONG          Reserved;
    SRV_COPYCHUNK  Chunk[1];    // Array
} SRV_COPYCHUNK_COPY, *PSRV_COPYCHUNK_COPY;

typedef struct _SRV_COPYCHUNK_RESPONSE {
    ULONG          ChunksWritten;
    ULONG          ChunkBytesWritten;
    ULONG          TotalBytesWritten;
} SRV_COPYCHUNK_RESPONSE, *PSRV_COPYCHUNK_RESPONSE;

これらのメンバーは、次のように記述できます。

メンバー	説明
SourceOffset	ソース ファイルの先頭からコピーするチャンクまでのオフセット (バイト単位)。
DestinationOffset	ターゲット ファイルの先頭からチャンクをコピーする場所までのオフセット (バイト単位)。
長さ	コピーするチャンク内のデータのバイト数。 0 より大きく、1 MB 以下である必要があります。 長さ * ChunkCount は 16 MB 以下である必要があります。
SourceFile	コピーするデータを含むソース ファイルを表すキー。 このキーは 、FSCTL_SRV_REQUEST_RESUME_KEYを通じて取得されます。
ChunkCount	コピーするチャンクの数。 0 より大きく、256 以下である必要があります。
予約	このメンバーは、システム用に予約されています。使用しないでください。
チャンク	ChunkCountSRV_COPYCHUNK 構造体の配列。コピーするチャンクごとに 1 つ。 この配列の長さ (バイト単位) は ChunkCount * sizeof(SRV_COPYCHUNK) である必要があります。
ChunksWritten	ERROR_INVALID_PARAMETERで操作が失敗した場合、この値は、サーバーが 1 つの要求で受け入れるチャンクの最大数 (256) を示します。 それ以外の場合、この値は正常に書き込まれたチャンクの数を示します。
ChunkBytesWritten	ERROR_INVALID_PARAMETERで操作が失敗した場合、この値は、サーバーが 1 つのチャンク (1 MB) で書き込むことが許可される最大バイト数を示します。 それ以外の場合、この値は、(部分的な書き込みが発生した場合に) 正常に処理されなかった最後のチャンクで正常に書き込まれたバイト数を示します。
TotalBytesWritten	ERROR_INVALID_PARAMETERで操作が失敗した場合、この値は、サーバーが 1 つの要求でコピーする最大バイト数 (16 MB) を示します。 それ以外の場合、この値は正常に書き込まれたバイト数を示します。

 

関連項目

DeviceIoControl

FSCTL_SRV_REQUEST_RESUME_KEY