DeviceIoControl-Funktion (ioapiset.h)

Sendet einen Steuerelementcode direkt an einen angegebenen Gerätetreiber, wodurch das entsprechende Gerät den entsprechenden Vorgang ausführen kann.

Weitere Informationen finden Sie im Beispiel "Zuweisen von Laufwerkbuchstaben".

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 auf dem 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. Um einen Gerätehandpunkt abzurufen, verwenden Sie die CreateFile-Funktion . Weitere Informationen finden Sie in den Hinweisen.

[in] dwIoControlCode

Der Steuerelementcode für den Vorgang. Dieser Wert identifiziert den spezifischen Vorgang, der ausgeführt werden soll, und den Typ des Geräts, auf dem sie ausgeführt werden soll.

Eine Liste der Steuerelementcodes finden Sie unter Hinweise. Die Dokumentation für jeden Steuerelementcode bietet Verwendungsdetails 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 daten empfängt, die im Ausgabepuffer gespeichert sind, in Bytes.

Wenn der Ausgabepuffer zu klein ist, um Daten zu empfangen, schlägt der Aufruf fehl, gibt GetLastErrorERROR_INSUFFICIENT_BUFFER zurück, und lpBytesReturned ist Null.

Wenn der Ausgabepuffer zu klein ist, um alle Daten zu halten, aber einige Einträge halten können, gibt einige Treiber so viel Daten wie passt zurück. In diesem Fall schlägt der Aufruf fehl, GetLastError gibt ERROR_MORE_DATA zurück, und lpBytesReturned gibt die Menge der empfangenen Daten an. Ihre Anwendung sollte DeviceIoControl erneut mit demselben Vorgang aufrufen, der einen neuen Ausgangspunkt angibt.

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

Wenn lpOverlapped nicht NULL 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. Um die Anzahl der zurückgegebenen Bytes abzurufen, rufen Sie GetOverlappedResult auf. Wenn hDevice einem I/O-Abschlussport zugeordnet ist, können Sie die Anzahl von Bytes abrufen, die durch Aufrufen von GetQueuedCompletionStatus zurückgegeben werden.

[in, out, optional] lpOverlapped

Ein Zeiger auf eine ÜBERLAPPENDE Struktur.

Wenn hDevice 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 ein Fehler auftritt.

Rückgabewert

Wenn der Vorgang erfolgreich abgeschlossen ist, ist der Rückgabewert nonzero (TRUE).

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

Bemerkungen

Zum Abrufen eines Handles auf dem Gerät 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 zum Angeben eines Gerätenamens das folgende Format:

\\.\DeviceName

DeviceIoControl kann einen Handle für ein bestimmtes Gerät akzeptieren. Wenn Sie beispielsweise ein Handle auf das logische Laufwerk A öffnen möchten: mit CreateFile, geben Sie \\.\a:. Alternativ können Sie die Namen \\.\PhysicalDrive0, \\.\PhysicalDrive1 und so weiter verwenden, um Handle für die physischen Laufwerke auf einem System zu öffnen.

Sie sollten die FILE_SHARE_READ und FILE_SHARE_WRITE Zugriffs flags angeben, wenn Sie CreateFile aufrufen, um einen Handle mit einem 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 beim Öffnen eines Gerätehandpunkts:

  • Der fdwCreate-Parameter muss OPEN_EXISTING angeben.
  • Der hTemplateFile-Parameter muss NULL sein.
  • Der fdwAttrsAndFlags-Parameter kann FILE_FLAG_OVERLAPPED angeben, um anzugeben, dass der zurückgegebene Handle in überlappenden (asynchronen) I/O-Vorgängen verwendet werden kann.
Eine Liste der unterstützten Steuerelementcodes finden Sie in den folgenden Themen:

Beispiele

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

Anforderungen

   
Unterstützte Mindestversion (Client) Windows XP
Unterstützte Mindestversion (Server) Windows Server 2003
Zielplattform Windows
Kopfzeile ioapiset.h (enthalten Windows.h)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

CreateEvent

CreateFile

Geräteeingabe- und Ausgabesteuerung (IOCTL)

GetOverlappedResult

GetQueuedCompletionStatus

ÜBERLAPPENDE

Beispiel für Laufwerkbuchstaben zuweisen