PFNKSDEVICEQUERYPOWER callback function (ks.h)

Article
03/15/2022

AVStream calls a minidriver's AVStrMiniDeviceQueryPower routine when it receives an IRP_MN_QUERY_POWER request.

Syntax

PFNKSDEVICEQUERYPOWER Pfnksdevicequerypower;

NTSTATUS Pfnksdevicequerypower(
  [in] PKSDEVICE Device,
  [in] PIRP Irp,
  [in] DEVICE_POWER_STATE DeviceTo,
  [in] DEVICE_POWER_STATE DeviceFrom,
  [in] SYSTEM_POWER_STATE SystemTo,
  [in] SYSTEM_POWER_STATE SystemFrom,
  [in] POWER_ACTION Action
)
{...}

Parameters

[in] Device

Pointer to the KSDEVICE structure that dispatched the IRP_MN_QUERY_POWER.

[in] Irp

Pointer to the IRP_MN_QUERY_POWER issued by Device.

[in] DeviceTo

The power state requested by the issuer of Irp.

[in] DeviceFrom

The current device power state.

[in] SystemTo

System state to transition to, specified when a system power state transition is being queried. This value is unspecified if the call is due to a device power state change query.

[in] SystemFrom

Current system state, specified when a system power state transition is being queried. This value is unspecified if the call is due to a device power state change query.

[in] Action

Specifies additional information about the requested transition. Possible values are enumerators of the POWER_ACTION type.

Return value

Should return STATUS_SUCCESS or the error code that was returned from the attempt to perform the operation. By returning STATUS_SUCCESS, the driver guarantees that it will not start any operation that would change its ability to set the requested power state. The driver should queue any IRP that would require such an operation until it completes a IRP_MN_SET_POWER that returns the device to an acceptable power state.

Remarks

The power manager or a device power policy owner sends an IRP_MN_QUERY_POWER request to determine whether it can change the system or device power state (for example, to go to sleep).

If a driver fails an IRP_MN_QUERY_POWER request for a system power state, the power manager typically responds by issuing an IRP_MN_SET_POWER. Usually, this IRP will reaffirm the current system state. However, it is possible that drivers might receive an IRP_MN_SET_POWER to the queried state or to some other intermediate state. Drivers should be prepared to handle these situations.

The minidriver specifies this routine's address in the QueryPower member of its KSDEVICE_DISPATCH structure.

This routine is optional.

Requirements

Requirement	Value
Minimum supported client	Available in Microsoft Windows XP and later operating systems and DirectX 8.0 and later DirectX versions.
Target Platform	Desktop
Header	ks.h (include Ks.h)