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 為零。

如果 lpOverlapped 參數為 Null， 則 lpBytesReturned 不能是 Null。 即使作業未傳回任何輸出資料， 而且 lpOutBuffer 參數為 Null， DeviceIoControl 仍會使用 lpBytesReturned。 在這類作業之後， lpBytesReturned 的值就沒有意義。

如果 lpOverlapped 不是 Null， lpBytesReturned 可以是 Null。 如果 lpOverlapped 不是 Null ，而且作業會傳回資料， 則 lpBytesReturned 在重迭的作業完成之前是無意義的。 若要擷取傳回的位元組數目，請呼叫 GetOverlappedResult 函式。 如果 hDevice 參數與 I/O 完成埠相關聯，您可以呼叫 GetQueuedCompletionStatus 函式來擷取傳回的位元組數目。

lpOverlapped [in]

重迭結構的指標。

如果 已開啟 hDevice 參數而不指定 FILE_FLAG_OVERLAPPED，則會忽略 lpOverlapped 。

如果使用 FILE_FLAG_OVERLAPPED 旗標開啟 hDevice ，則會以重迭的 ( 非同步) 作業來執行作業。 在此情況下， lpOverlapped 必須指向包含事件物件控制碼的有效 OVERLAPPED 結構。 否則，函式會以無法預測的方式失敗。

對於重迭的作業， DeviceIoControl 會立即傳回，而且當作業完成時，事件物件會發出訊號。 否則，函式不會在作業完成或發生錯誤之前傳回。

傳回值

如果作業順利完成， DeviceIoControl 會傳回非零值。

如果作業失敗或擱置中， DeviceIoControl 會傳回零。 若要取得擴充的錯誤資訊，請呼叫 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;

這些成員可以如下所述。

member	描述
SourceOffset	從來源檔案開頭到要複製之區塊的位移，以位元組為單位。
DestinationOffset	從目標檔案開頭到要複製區塊位置的位移，以位元組為單位。
長度	要複製之區塊中的資料位元組數目。 必須大於零，且小於或等於 1 MB。 長度 * ChunkCount必須小於或等於 16 MB。
SourceFile	索引鍵，表示要複製之資料的來源檔案。 此金鑰是透過 FSCTL_SRV_REQUEST_RESUME_KEY取得。
ChunkCount	要複製的區塊數目。 必須大於零，且小於或等於 256。
保留	此成員保留供系統使用;請勿使用。
塊	ChunkCountSRV_COPYCHUNK結構的陣列，每個要複製的區塊各一個。 此陣列的長度，以位元組為單位必須是 ChunkCount * sizeof (SRV_COPYCHUNK) 。
ChunksWritten	如果作業失敗 ，ERROR_INVALID_PARAMETER，這個值表示伺服器將在單一要求中接受的最大區塊數目，也就是 256。 否則，這個值表示已成功寫入的區塊數目。
ChunkBytesWritten	如果作業失敗 ，ERROR_INVALID_PARAMETER，這個值表示伺服器將允許以單一區塊寫入的最大位元組數目，也就是 1 MB。 否則，如果發生部分) 寫入，這個值會指出在未成功處理的最後一個區塊中成功寫入的位元組數目 (。
TotalBytesWritten	如果作業失敗 ，ERROR_INVALID_PARAMETER，這個值表示伺服器將在單一要求中複製的最大位元組數目，也就是 16 MB。 否則，這個值表示已成功寫入的位元組數目。

 

另請參閱

DeviceIoControl

FSCTL_SRV_REQUEST_RESUME_KEY