DeviceIoControl-Funktion (ioapiset.h)

Artikel
03/01/2024

Sendet einen Steuercode direkt an einen angegebenen Gerätetreiber, wodurch das entsprechende Gerät den entsprechenden Vorgang ausführt.

Weitere Informationen finden Sie im Beispiel Zum Zuweisen des Laufwerkbuchstabens.

Syntax

BOOL DeviceIoControl(
  [in]                HANDLE       hDevice,
  [in]                DWORD        dwIoControlCode,
  [in, optional]      LPVOID       lpInBuffer,
  [in]                DWORD        nInBufferSize,
  [out, optional]     LPVOID       lpOutBuffer,
  [in]                DWORD        nOutBufferSize,
  [out, optional]     LPDWORD      lpBytesReturned,
  [in, out, optional] LPOVERLAPPED lpOverlapped
);

Parameter

[in] hDevice

Ein Handle für das Gerät, auf dem der Vorgang ausgeführt werden soll. Das Gerät ist in der Regel ein Volume, ein Verzeichnis, eine Datei oder ein Stream. Verwenden Sie zum Abrufen eines Gerätehandles die CreateFile-Funktion . Weitere Informationen finden Sie in den Hinweisen.

[in] dwIoControlCode

Der Steuerungscode für den Vorgang. Dieser Wert gibt den auszuführenden Vorgang und den Typ des Geräts an, auf dem er ausgeführt werden soll.

Eine Liste der Steuerelementcodes finden Sie unter Hinweise. Die Dokumentation für jeden Steuerelementcode enthält Nutzungsdetails für die Parameter lpInBuffer, nInBufferSize, lpOutBuffer und nOutBufferSize .

[in, optional] lpInBuffer

Ein Zeiger auf den Eingabepuffer, der die zum Ausführen des Vorgangs erforderlichen Daten enthält. Das Format dieser Daten hängt vom Wert des dwIoControlCode-Parameters ab.

Dieser Parameter kann NULL sein, wenn dwIoControlCode einen Vorgang angibt, der keine Eingabedaten erfordert.

[in] nInBufferSize

Die Größe des Eingabepuffers in Bytes.

[out, optional] lpOutBuffer

Ein Zeiger auf den Ausgabepuffer, der die vom Vorgang zurückgegebenen Daten empfangen soll. Das Format dieser Daten hängt vom Wert des dwIoControlCode-Parameters ab.

Dieser Parameter kann NULL sein, wenn dwIoControlCode einen Vorgang angibt, der keine Daten zurückgibt.

[in] nOutBufferSize

Die Größe des Ausgabepuffers in Bytes.

[out, optional] lpBytesReturned

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

Wenn der Ausgabepuffer für den Empfang von Daten zu klein ist, schlägt der Aufruf fehl, GetLastError gibt ERROR_INSUFFICIENT_BUFFER zurück, und lpBytesReturned ist null.

Wenn der Ausgabepuffer zu klein ist, um alle Daten aufzunehmen, aber einige Einträge enthalten kann, geben einige Treiber so viele Daten wie möglich zurück. In diesem Fall schlägt der Aufruf fehl, GetLastError gibt ERROR_MORE_DATA zurück, und lpBytesReturned gibt die empfangene Datenmenge an. Ihre Anwendung sollte DeviceIoControl erneut mit demselben Vorgang aufrufen und einen neuen Ausgangspunkt angeben.

Wenn lpOverlappedNULL ist, kann lpBytesReturned nicht NULL sein. Auch wenn ein Vorgang keine Ausgabedaten zurückgibt und lpOutBufferNULL ist, verwendet DeviceIoControllpBytesReturned. Nach einem solchen Vorgang ist der Wert von lpBytesReturned bedeutungslos.

Wenn lpOverlappedNULL ist, kann lpBytesReturnedNULL sein. Wenn dieser Parameter nicht NULL ist und der Vorgang Daten zurückgibt, ist lpBytesReturned bedeutungslos, bis der überlappende Vorgang abgeschlossen ist. Rufen Sie GetOverlappedResult auf, um die Anzahl der zurückgegebenen Bytes abzurufen. Wenn hDevice einem E/A-Abschlussport zugeordnet ist, können Sie die Anzahl der zurückgegebenen Bytes abrufen, indem Sie GetQueuedCompletionStatus aufrufen.

[in, out, optional] lpOverlapped

Ein Zeiger auf eine Struktur OVERLAPPED.

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

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

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

Rückgabewert

Wenn der Vorgang erfolgreich abgeschlossen wird, ist der Rückgabewert ungleich null (TRUE).

Wenn der Vorgang fehlschlägt oder aussteht, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Um ein Handle für das Gerät abzurufen, müssen Sie die CreateFile-Funktion entweder mit dem Namen eines Geräts oder dem Namen des Treibers aufrufen, der einem Gerät zugeordnet ist. Verwenden Sie das folgende Format, um einen Gerätenamen anzugeben:

\\.\DeviceName

DeviceIoControl kann ein Handle für ein bestimmtes Gerät akzeptieren. Um beispielsweise ein Handle für das logische Laufwerk A: mit CreateFile zu öffnen, geben Sie \\.\a: an. Alternativ können Sie die Namen \\.\PhysicalDrive0, \\.\PhysicalDrive1 usw. verwenden, um Handles für die physischen Laufwerke auf einem System zu öffnen.

Sie sollten die FILE_SHARE_READ und FILE_SHARE_WRITE Zugriffsflags angeben, wenn Sie CreateFile aufrufen, um ein Handle für einen Gerätetreiber zu öffnen. Wenn Sie jedoch eine Kommunikationsressource öffnen, z. B. einen seriellen Port, müssen Sie den exklusiven Zugriff angeben. Verwenden Sie die anderen CreateFile-Parameter wie folgt, wenn Sie ein Gerätehandle öffnen:

Der parameter fdwCreate muss OPEN_EXISTING angeben.
Der hTemplateFile-Parameter muss NULL sein.
Der fdwAttrsAndFlags-Parameter kann FILE_FLAG_OVERLAPPED angeben, um anzugeben, dass das zurückgegebene Handle in überlappenden (asynchronen) E/A-Vorgängen verwendet werden kann.

Listen mit unterstützten Steuerelementcodes finden Sie in den folgenden Themen:

Beispiele

Ein Beispiel, das DeviceIoControl verwendet, finden Sie unter Aufrufen von DeviceIoControl.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP
Unterstützte Mindestversion (Server)	Windows Server 2003
Zielplattform	Windows
Kopfzeile	ioapiset.h (Einschließen von Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll