IOCTL_ACPI_ENUM_CHILDREN IOCTL (acpiioct.h)
Запрос IOCTL_ACPI_ENUM_CHILDREN управления устройством можно использовать для перечисления пути и имени устройств или именованных дочерних объектов в пространстве имен ACPI устройства, на которое отправляется этот запрос. Драйвер должен вызвать IoBuildDeviceIoControlRequest и передать следующие входные и выходные параметры для построения этого запроса.
Основной код
Входной буфер
Задайте входные параметры IoBuildDeviceIoControlRequest следующим образом:
- IoControlCode имеет значение IOCTL_ACPI_ENUM_CHILDREN.
- DeviceObject — это указатель на физический объект устройства (PDO).
- InputBuffer — это указатель на структуру ACPI_ENUM_CHILDREN_INPUT_BUFFER переменной длины.
- InputBufferLength устанавливается в размере входного буфера в байтах, предоставляемого InputBuffer.
- OutputBufferLength предоставляет размер выходного буфера в байтах, предоставляемый OutputBuffer.
- Параметр InternalDeviceIoControl имеет значение FALSE.
- Событие — это указатель на выделенный вызывающим и инициализированный объект события.
Длина входного буфера
InputBufferLength устанавливается в размере входного буфера в байтах, предоставляемого InputBuffer.
Выходной буфер
Задайте выходные параметры IoBuildDeviceIoControlRequest следующим образом:
- OutputBuffer предоставляет указатель на структуру ACPI_ENUM_CHILDREN_OUTPUT_BUFFER переменной длины, в которой драйвер ACPI возвращает путь и имя перечисляемых дочерних устройств.
- IoStatusBlock имеет IO_STATUS_BLOCK структуру.
Длина выходного буфера
OutputBufferLength предоставляет размер выходного буфера в байтах, предоставляемый OutputBuffer.
Блок состояния
Если запрос выполнен успешно, ioStatusBlock-Status> получает значение STATUS_SUCCESS; в противном случае члену Status присваивается код ошибки. Если выходной буфер недостаточно велик, чтобы содержать заголовок буфера, для элемента Status устанавливается значение STATUS_BUFFER_TOO_SMALL. Если выходной буфер достаточно велик, чтобы содержать заголовок выходного буфера, но не достаточно велик, чтобы содержать пути и имена всех перечисляемых дочерних объектов, то для элемента Status устанавливается значение STATUS_BUFFER_OVERFLOW а для OutputBuffer-NumberOfChildren> устанавливается необходимая длина выходного буфера.
Если запрос выполнен успешно, для элемента IoStatusBlock-Information> устанавливается количество байтов, возвращаемых в выходном буфере; в противном случае элементу Information присваивается значение 0.
Комментарии
IOCTL_ACPI_ENUM_CHILDREN возвращает структуру ACPI_ENUM_CHILDREN_OUTPUT_BUFFER переменной длины, содержащую массив структур ACPI_ENUM_CHILD переменной длины, каждая из которых возвращает полный путь и имя объекта в пространстве имен ACPI устройства, на которое был отправлен запрос. Объекты, перечисляемые этим запросом, зависят от настройки элемента Flags предоставленной входной структуры ACPI_ENUM_CHILDREN_INPUT_BUFFER следующим образом:
Если выходной буфер, выделенный драйвером, недостаточно велик для возврата всех запрошенных дочерних имен, драйвер ACPI не возвращает дочерние имена и задает элементу Status IO_STATUS_BLOCK для запроса STATUS_BUFFER_OVERFLOW. В этом случае, если размер выходного буфера в байтах равен по крайней мере sizeof(ACPI_ENUM_CHILDREN_OUTPUT_BUFFER_SIGNATURE), драйвер ACPI также устанавливает для параметра NumberOfChildren размер в байтах, необходимый для получения запрошенных путей и имен.
Драйвер обычно использует последовательность из двух IOCTL_ACPI_ENUM_CHILDREN запросов для перечисления дочерних объектов, представляющих интерес. Драйвер отправляет первый запрос на получение размера выходного буфера, необходимого для хранения пути и имени всех запрошенных объектов. Драйвер отправляет второй запрос на возврат пути и имени объектов в выходном буфере.
Дополнительные сведения о перечислении дочерних устройств устройства см. в разделе Перечисление дочерних устройств и методов управления.
IOCTL_ACPI_ENUM_CHILDREN можно использовать только на DISPATCH_LEVEL IRQL< .
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows Vista и более поздние версии Windows. |
| Верхняя часть | acpiioct.h (включая Acpiioct.h) |