IOCTL_ACPI_ENUM_CHILDREN IOCTL (acpiioct.h)
Die IOCTL_ACPI_ENUM_CHILDREN Gerätesteuerungsanforderung kann verwendet werden, um den Pfad und Namen von Geräten oder benannten untergeordneten Objekten im ACPI-Namespace des Geräts aufzulisten, an das diese Anforderung gesendet wird. Ein Treiber sollte IoBuildDeviceIoControlRequest aufrufen und die folgenden Eingabe- und Ausgabeparameter übergeben, um diese Anforderung zu erstellen.
Hauptcode
Eingabepuffer
Legen Sie die IoBuildDeviceIoControlRequest-Eingabeparameter wie folgt fest:
- IoControlCode ist auf IOCTL_ACPI_ENUM_CHILDREN festgelegt.
- DeviceObject ist auf einen Zeiger auf das objekt des physischen Geräts (PDO) des Geräts festgelegt.
- InputBuffer ist auf einen Zeiger auf eine ACPI_ENUM_CHILDREN_INPUT_BUFFER-Struktur variabler Länge festgelegt.
- InputBufferLength wird auf die Größe des Eingabepuffers in Bytes festgelegt, der von InputBuffer bereitgestellt wird.
- OutputBufferLength stellt die Größe des von OutputBuffer bereitgestellten Ausgabepuffers in Bytes bereit.
- InternalDeviceIoControl ist auf FALSE festgelegt.
- Das Ereignis wird auf einen Zeiger auf ein vom Aufrufer zugeordnetes und initialisiertes Ereignisobjekt festgelegt.
Länge des Eingabepuffers
InputBufferLength wird auf die Größe des Eingabepuffers in Bytes festgelegt, der von InputBuffer bereitgestellt wird.
Ausgabepuffer
Legen Sie die IoBuildDeviceIoControlRequest-Ausgabeparameter wie folgt fest:
- OutputBuffer stellt einen Zeiger auf eine ACPI_ENUM_CHILDREN_OUTPUT_BUFFER Struktur mit variabler Länge bereit, in der der ACPI-Treiber den Pfad und Namen der aufgezählten untergeordneten Geräte zurückgibt.
- IoStatusBlock ist auf eine IO_STATUS_BLOCK-Struktur festgelegt.
Länge des Ausgabepuffers
OutputBufferLength stellt die Größe des von OutputBuffer bereitgestellten Ausgabepuffers in Bytes bereit.
Statusblock
Wenn die Anforderung erfolgreich ist, wird IoStatusBlock-Status> auf STATUS_SUCCESS festgelegt. Andernfalls wird der Status-Member auf einen Fehlercode festgelegt. Wenn der Ausgabepuffer nicht groß genug ist, um den Pufferheader zu enthalten, wird der Statusmember auf STATUS_BUFFER_TOO_SMALL festgelegt. Wenn der Ausgabepuffer groß genug ist, um den Ausgabepufferheader zu enthalten, aber nicht groß genug ist, um die Pfade und Namen aller aufgelisteten untergeordneten Objekte zu enthalten, wird der Status-Member auf STATUS_BUFFER_OVERFLOW und OutputBuffer-NumberOfChildren> auf die erforderliche Länge des Ausgabepuffers festgelegt.
Wenn die Anforderung erfolgreich ist, wird der IoStatusBlock-Information-Member> auf die Anzahl der Bytes festgelegt, die im Ausgabepuffer zurückgegeben werden. Andernfalls wird der Information-Member auf 0 (null) festgelegt.
Hinweise
IOCTL_ACPI_ENUM_CHILDREN gibt eine ACPI_ENUM_CHILDREN_OUTPUT_BUFFER-Struktur mit variabler Länge zurück, die ein Array von Strukturen mit variabler Länge ACPI_ENUM_CHILD enthält, die jeweils den vollqualifizierten Pfad und Namen eines Objekts im ACPI-Namespace des Geräts zurückgibt, an das die Anforderung gesendet wurde. Die Objekte, die diese Anforderung aufzählt, hängen wie folgt von der Einstellung des Flags-Elements der angegebenen Eingabestruktur ACPI_ENUM_CHILDREN_INPUT_BUFFER ab:
Wenn der Ausgabepuffer, den der Treiber ordnet, nicht groß genug ist, um alle angeforderten untergeordneten Namen zurückzugeben, gibt der ACPI-Treiber keine untergeordneten Namen zurück und legt den Status-Member des IO_STATUS_BLOCK für die Anforderung auf STATUS_BUFFER_OVERFLOW fest. Wenn in diesem Fall die Größe des Ausgabepuffers in Bytes mindestens sizeof(ACPI_ENUM_CHILDREN_OUTPUT_BUFFER_SIGNATURE) beträgt, legt der ACPI-Treiber NumberOfChildren auch auf die Größe in Bytes fest, die zum Abrufen der angeforderten Pfade und Namen erforderlich ist.
Ein Treiber verwendet in der Regel eine Sequenz von zwei IOCTL_ACPI_ENUM_CHILDREN Anforderungen, um die untergeordneten Objekte von Interesse aufzulisten. Der Treiber sendet die erste Anforderung, um die Größe des Ausgabepuffers abzurufen, der den Pfad und Namen aller angeforderten Objekte enthalten muss. Der Treiber sendet die zweite Anforderung, um den Pfad und namen der Objekte im Ausgabepuffer zurückzugeben.
Weitere Informationen zum Auflisten untergeordneter Geräte eines Geräts finden Sie unter Auflisten untergeordneter Geräte und Steuerungsmethoden.
IOCTL_ACPI_ENUM_CHILDREN können nur im IRQL-DISPATCH_LEVEL< verwendet werden.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows Vista und höhere Versionen von Windows. |
| Kopfzeile | acpiioct.h (include Acpiioct.h) |