IoQueryDeviceDescription

IoQueryDeviceDescription

NTSTATUS
IoQueryDeviceDescription(
IN PINTERFACE_TYPE BusType,/* optional */
IN PULONG BusNumber,/* optional */
IN PCONFIGURATION_TYPE ControllerType,/* optional */
IN PULONG ControllerNumber,/* optional */
IN PCONFIGURATION_TYPE PeripheralType,/* optional */
IN PULONG PeripheralNumber,/* optional */
IN PIO_QUERY_DEVICE_ROUTINE CalloutRoutine,
IN PVOID Context
);

IoQueryDeviceDescription retrieves hardware configuration information about a given bus, controller or peripheral object, or any combination of these three types from the \Registry\Machine\Hardware\Description tree.

Parameters

BusType

Specifies the type of bus searched for in the registry's hardware description tree which can be one of the following values: Internal, Isa, Eisa, MicroChannel TurboChannel, or PCIBus. However, additional types of buses will be supported in future versions of Windows NT. The upper bound on the types supported is always MaximumInterfaceType.

BusNumber

Specifies the zero-based and system-assigned number of the bus. This parameter is optional. If BusType is supplied but no specific BusNumber is specified, information on all buses of type BusType is returned.

ControllerType

Specifies the type of controller for which to return information. It can be one of the following: DiskController, TapeController, CdRomController, WormController, SerialController, NetworkController, DisplayController, ParallelController, PointerController, KeyboardController, AudioController, or OtherController. If no ControllerType or PeripheralType value is specified, only bus information is returned.

ControllerNumber

Specifies the zero-based number of the controller. This parameter is optional. If ControllerType is supplied but a specific ControllerNumber is not, information on all controllers of type ControllerType is returned.

PeripheralType

Specifies the type of peripheral for which to return information. It can be one of the following: DiskPeripheral, FloppyDiskPeripheral, TapePeripheral, ModemPeripheral, MonitorPeripheral, PrinterPeripheral, PointerPeripheral, KeyboardPeripheral, TerminalPeripheral, OtherPeripheral, LinePeripheral, or NetworkPeripheral. If no peripheral type is specified, only bus information and controller information are returned.

PeripheralNumber

Specifies the zero-based number of the peripheral. This parameter is optional. If PeripheralType is supplied but a specific PeripheralNumber is not, information on all peripherals of type PeripheralType is returned.

CalloutRoutine

Points to a driver-supplied routine to be called when the requested information has been located. This routine is declared as follows:

NTSTATUS

(*PIO_QUERY_DEVICE_ROUTINE) (

IN PVOID Context,

IN PUNICODE_STRING PathName,

IN INTERFACE_TYPE BusType,

IN ULONG BusNumber,

IN PKEY_VALUE_FULL_INFORMATION *BusInformation,

IN CONFIGURATION_TYPE ControllerType,

IN ULONG ControllerNumber,

IN PKEY_VALUE_FULL_INFORMATION *ControllerInformation,

IN CONFIGURATION_TYPE PeripheralType,

IN ULONG PeripheralNumber,

IN PKEY_VALUE_FULL_INFORMATION *PeripheralInformation

);

Context

Specifies the context value that is passed to the callback routine.

Return Value

IoQueryDeviceDescription returns the STATUS_XXX returned by the callback routine.

Comments

This routine queries the registry for description(s) of the given bus type and number, controller type and number, and/or peripheral type and number. The information retrieved is passed to a driver-supplied ConfigCallback routine.

While the bus, controller, and peripheral parameters are each optional, the caller must supply at least one type parameter.

On entry, the driver's ConfigCallback routine is given pointers to registry keys for bus, controller, and/or peripheral information. Each such pointer is actually a pointer to an array of IO_QUERY_DEVICE_DATA_FORMAT pointers identified as follows:

IoQueryDeviceIdentifier
IoQueryDeviceConfigurationData
IoQueryDeviceComponentInformation

When the ConfigCallback routine returns control, these pointers become invalid. The driver's ConfigCallback routine should save pertinent information about the I/O ports or device memory, the bus-relative interrupt vector or IRQL, and/or the DMA channel or port, that is available in the registry for the DriverEntry routine to use in subsequent calls to HalTranslateBusAddress (and possibly MmMapIoSpace), HalGetInterruptVector, and/or HalGetAdapter.

As an alternative, a driver can call HalGetBusData or HalGetBusDataByOffset to locate its device(s) and to retrieve bus-relative configuration information. Then, the driver can call IoAssignResources, which checks the input resource list against the hardware configuration information in the registry and also encapsulates most of the functionality of IoReportResourceUsage. As an alternative, drivers of PCI-type devices can call HalAssignSlotResources.

Callers of IoQueryDeviceDescription must be running at IRQL PASSIVE_LEVEL.