IOCTL_COPYCHUNK Steuerelementcode

Der IOCTL_COPYCHUNK-Steuerelementcode initiiert eine serverseitige Kopie eines Datenbereichs, auch als "Chunk" bezeichnet.

Um diesen Vorgang auszuführen, rufen Sie die DeviceIoControl-Funktion mit den folgenden Parametern auf.

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

Parameter

hDevice [in]

Ein Handle an die Datei, die das Ziel des serverseitigen Kopiervorgangs ist. Um diesen Handle abzurufen, rufen Sie die CreateFile-Funktion auf.

dwIoControlCode [in]

Der Steuerelementcode für den Vorgang. Verwenden Sie IOCTL_COPYCHUNK für diesen Vorgang.

lpInBuffer

Ein Zeiger auf den Eingabepuffer, eine SRV_COPYCHUNK_COPY Struktur. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

nInBufferSize [in]

Die Größe des Eingabepuffers in Bytes.

lpOutBuffer [out]

Ein Zeiger auf den Ausgabepuffer, eine SRV_COPYCHUNK_RESPONSE Struktur. Weitere Informationen finden Sie im Abschnitt mit Hinweisen.

nOutBufferSize [in]

Die Größe des Ausgabepuffers in Bytes.

lpBytesReturned [out]

Ein Zeiger auf eine Variable, die die Größe der daten empfängt, die im Ausgabepuffer gespeichert sind, in Bytes.

Wenn der Ausgabepuffer zu klein ist, schlägt der Aufruf fehl, gibt die GetLastError-FunktionERROR_INSUFFICIENT_BUFFER zurück, und lpBytesReturned ist Null.

Wenn der lpOverlapped-ParameterNULL ist, kann lpBytesReturned nicht NULL sein. Selbst wenn ein Vorgang keine Ausgabedaten zurückgibt und der lpOutBuffer-ParameterNULL ist, verwendet DeviceIoControllpBytesReturned. Nach einem solchen Vorgang ist der Wert von lpBytesReturned bedeutungslos .

Wenn lpOverlapped nicht NULL ist, kann lpBytesReturnedNULL sein. Wenn lpOverlapped nicht NULL ist und der Vorgang Daten zurückgibt, ist lpBytesReturned bedeutungslos , bis der überlappende Vorgang abgeschlossen ist. Um die Anzahl der zurückgegebenen Bytes abzurufen, rufen Sie die GetOverlappedResult-Funktion auf. Wenn der hDevice-Parameter einem I/O-Abschlussport zugeordnet ist, können Sie die Anzahl der zurückgegebenen Bytes abrufen, indem Sie die Funktion GetQueuedCompletionStatus aufrufen.

lpOverlapped [in]

Ein Zeiger auf eine ÜBERLAPPENDE Struktur.

Wenn der hDevice-Parameter geöffnet wurde, ohne FILE_FLAG_OVERLAPPED anzugeben, wird lpOverlapped ignoriert.

Wenn hDevice mit dem FILE_FLAG_OVERLAPPED-Flag geöffnet wurde, wird der Vorgang als überlappender (asynchroner) Vorgang ausgeführt. In diesem Fall muss lpOverlapped auf eine gültige ÜBERLAPPENDE Struktur verweisen, die einen Handle auf ein Ereignisobjekt enthält. Andernfalls schlägt die Funktion auf unvorhersehbare Weise fehl.

Bei überlappenden Vorgängen gibt DeviceIoControl sofort zurück, und das Ereignisobjekt wird signalisiert, wenn der Vorgang abgeschlossen wurde. Andernfalls wird die Funktion erst zurückgegeben, wenn der Vorgang abgeschlossen wurde oder bis ein Fehler auftritt.

Rückgabewert

Wenn der Vorgang erfolgreich abgeschlossen ist, gibt DeviceIoControl einen nichtzero-Wert zurück.

Wenn der Vorgang fehlschlägt oder aussteht, gibt DeviceIoControl null zurück. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Bemerkungen

Dieser Steuerelementcode verfügt über keine zugeordnete Headerdatei. Sie müssen den Steuerelementcode und die Datenstrukturen wie folgt definieren.

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

Diese Mitglieder können wie folgt beschrieben werden.

Member	Beschreibung
SourceOffset	Der Offset in Bytes vom Anfang der Quelldatei bis zum kopierten Teil.
DestinationOffset	Der Offset in Bytes vom Anfang der Zieldatei bis zum Speicherort, an dem der Teil kopiert werden soll.
Länge	Die Anzahl der Daten in der zu kopierenden Blöcke. Muss größer als null und kleiner als oder gleich 1 MB sein. Länge * ChunkCount muss kleiner oder gleich 16 MB sein.
Sourcefile	Ein Schlüssel, der die Quelldatei mit den zu kopierenden Daten darstellt. Dieser Schlüssel wird über FSCTL_SRV_REQUEST_RESUME_KEY abgerufen.
ChunkCount	Die Anzahl der zu kopierenden Blöcke. Muss größer als null und kleiner sein als oder gleich 256.
Reserviert	Dieses Mitglied ist für die Systemverwendung reserviert; verwenden Sie nicht.
Stück	Ein Array von ChunkCountSRV_COPYCHUNK Strukturen, eine für jeden Teil, der kopiert werden soll. Die Länge in Bytes dieses Arrays muss ChunkCount * sizeof(SRV_COPYCHUNK) sein.
ChunksWritten	Wenn der Vorgang mit ERROR_INVALID_PARAMETER fehlgeschlagen ist, gibt dieser Wert die maximale Anzahl von Blöcken an, die der Server in einer einzelnen Anforderung akzeptiert, was 256 ist. Andernfalls gibt dieser Wert die Anzahl von Blöcken an, die erfolgreich geschrieben wurden.
ChunkBytesWritten	Wenn der Vorgang mit ERROR_INVALID_PARAMETER fehlgeschlagen ist, gibt dieser Wert die maximale Anzahl von Bytes an, die der Server in einem einzelnen Abschnitt geschrieben werden kann, was 1 MB ist. Andernfalls gibt dieser Wert die Anzahl der Bytes an, die erfolgreich in den letzten Abschnitten geschrieben wurden, die nicht erfolgreich verarbeitet wurden (wenn ein Teilschreib aufgetreten ist).
TotalBytesWritten	Wenn der Vorgang mit ERROR_INVALID_PARAMETER fehlgeschlagen ist, gibt dieser Wert die maximale Anzahl von Bytes an, die der Server in einer einzelnen Anforderung kopiert, was 16 MB ist. Andernfalls gibt dieser Wert die Anzahl der Bytes an, die erfolgreich geschrieben wurden.

 

Weitere Informationen

Deviceiocontrol

FSCTL_SRV_REQUEST_RESUME_KEY