HwVidQueryDeviceCallback

VP_STATUS HwVidQueryDeviceCallback(

PVOID  HwDeviceExtension,
PVOID  Context,
VIDEO_DEVICE_DATA_TYPE  DeviceDataType,
PVOID  Identifier,
ULONG  IdentifierLength,
PVOID  ConfigurationData,
ULONG  ConfigurationDataLength,
PVOID  ComponentInformation,
ULONG  ComponentInformationLength
);

HwVidQueryDeviceCallback is passed in a call to VideoPortGetDeviceData from the miniport’s HwVidFindAdapter function. VideoPortGetDeviceData calls HwVidQueryDeviceCallback after collecting available configuration information under the \Registry\Machine\Hardware\Description node of the registry.

Parameters

HwDeviceExtension

Points to the miniport driver’s per-adapter storage area.

Context

Points to the context value set up by HwVidFindAdapter. Usually, it points to the VIDEO_PORT_CONFIG_INFO buffer or to an offset in that buffer.

DeviceDataType

Specifies the type of configuration information that was requested, which is usually one of the following:

VpBusData
VpControllerData
VpMonitorData

The VpControllerData and VpMonitorData values have meaning only on ARC-compliant (RISC) platforms. Miniport drivers of x86-type video adapters usually specify VpBusData, particularly for adapters on EISA or MCA buses. The VpMachineData value is defined for future versions of Windows NT®.

Identifier

Points to the name of the device as determined by the ARC firmware. This parameter should be used only on ARC-compliant platforms. Otherwise, this pointer should be NULL.

IdentifierLength

Specifies the size in bytes of the buffered Identifier string. The value should be zero if the machine is not ARC-compliant.

ConfigurationData

Points to hardware configuration data. The format of this data is determined by the specified DeviceDataType and by the AdapterInterfaceType value in the VIDEO_PORT_CONFIG_INFO.

ConfigurationDataLength

Specifies the size in bytes of the ConfigurationData buffer. In effect, this indicates how much information was collected from the registry and stored in the ConfigurationData buffer allocated by VideoPortGetDeviceBase.

ComponentInformation

Is reserved for system use.

ComponentInformationLength

Is reserved for system use.

Return Value

HwVidQueryDeviceCallback returns the status of the operation.

Comments

HwVidQueryDeviceCallback examines the ConfigurationData, collected from the registry by VideoPortGetDeviceData. It uses this information to locate an adapter it can support, to configure its adapter, and, possibly, to fill in missing configuration information in the VIDEO_PORT_CONFIG_INFO structure.

HwVidQueryDeviceCallback cannot pass access range values found in the ConfigurationData to any VideoPortReadXxx or VideoPortWriteXxx directly; such addresses first must be mapped by calling VideoPortGetDeviceBase.

If the ConfigurationData buffer has no access range information and the miniport’s HwVidFindAdapter function has not already called VideoPortGetBusData (or VideoPortGetAccessRanges), its HwVidQueryDeviceCallback function can call VideoPortGetBusData. Access range information returned by VideoPortGetBusData also must be passed to VideoPortVerifyAccessRanges.

If VideoPortVerifyAccessRanges returns NO_ERROR, the miniport driver can call VideoPortGetDeviceBase to obtain mapped logical addresses that it can use to communicate with the adapter by calling the VideoPortReadXxx and/or VideoPortWriteXxx functions.

If it cannot get bus-relative access ranges values by calling VideoPortGetDeviceData, VideoPortGetBusData, or VideoPortGetAccessRanges, a miniport driver can use a set of driver-supplied default access-range values to find its adapter. In these circumstances, the miniport must call VideoPortVerifyAccessRanges with the miniport-supplied access ranges, and, then call VideoPortGetDeviceBase only if VideoPortVerifyAccessRanges returned NO_ERROR. If a call to VideoPortVerifyAccessRanges is unsuccessful, a given bus-relative range is already in use by the driver of another device.

See Also

VideoPortGetAccessRanges, VideoPortGetBusData, VideoPortGetDeviceBase, VideoPortGetDeviceData, VideoPortVerifyAccessRanges