PO_FX_POWER_CONTROL_CALLBACK callback function (wdm.h)

Article
02/28/2023

The PowerControlCallback callback routine performs a power control operation that is requested by the power management framework (PoFx).

Syntax

PO_FX_POWER_CONTROL_CALLBACK PoFxPowerControlCallback;

NTSTATUS PoFxPowerControlCallback(
                  PVOID DeviceContext,
  [in]            LPCGUID PowerControlCode,
  [in, optional]  PVOID InBuffer,
  [in]            SIZE_T InBufferSize,
  [out, optional] PVOID OutBuffer,
  [in]            SIZE_T OutBufferSize,
  [out, optional] PSIZE_T BytesReturned
)
{...}

Parameters

DeviceContext

[in] PowerControlCode

A pointer to the power control code. This code is a GUID value that specifies the requested operation.

[in, optional] InBuffer

A pointer to the buffer that contains the input data for the operation. The format for the data in this buffer depends on the power control code specified by the PowerControlCode parameter. The InBuffer parameter is optional and can be specified as NULL if the specified operation requires no input data.

[in] InBufferSize

The size, in bytes, of the input buffer that is pointed to by the InBuffer parameter. If InBuffer is NULL, this parameter is zero.

[out, optional] OutBuffer

A pointer to the buffer to which the callback routine writes the output data from the operation. The format for the data in this buffer depends on the power control code specified by the PowerControlCode parameter. The OutBuffer parameter is optional and can be specified as NULL if the specified operation produces no output data.

[in] OutBufferSize

The size, in bytes, of the output buffer that is pointed to by the OutBuffer parameter. If OutBuffer is NULL, this parameter is zero.

[out, optional] BytesReturned

A pointer to a location into which the routine writes the number of bytes of data that were written to the buffer that is pointed to by OutBuffer. The number of bytes written must be less than or equal to OutBufferSize. This parameter is optional and can be specified as NULL if the caller does not need to know how many bytes were written to the output buffer.

Return value

The PowerControlCallback routine returns STATUS_SUCCESS if the call is successful. Otherwise, it returns an appropriate error code.

Remarks

PoFx calls this routine to send a power control request directly to the device driver. A power control request is similar to an I/O control request (IOCTL). Unlike an IOCTL, however, a power control request is sent directly to the driver and is not observed by other device drivers in the device stack. During a PowerControlCallback call, the driver synchronously performs the requested operation.

This routine is optional. A device driver that does not support power control operations is not required to implement a PowerControlCallback routine.

The device driver can call the PoFxPowerControl routine to send a power control request to PoFx.

For more information about power control requests, see PoFxPowerControl.

Examples

To define a PowerControlCallback callback routine, you must first provide a function declaration that identifies the type of callback routine you're defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a PowerControlCallback callback routine that is named MyPowerControlCallback, use the PO_FX_POWER_CONTROL_CALLBACK type as shown in this code example:

PO_FX_POWER_CONTROL_CALLBACK MyPowerControlCallback;

Then, implement your callback routine as follows:

_Use_decl_annotations_
NTSTATUS
  MyPowerControlCallback(
    PVOID Context,
    LPCGUID PowerControlCode,
    PVOID InBuffer,
    SIZE_T InBufferSize,
    PVOID OutBuffer,
    SIZE_T OutBufferSize,
    PSIZE_T BytesReturned
    )
  {
      // Function body
  }

The PO_FX_POWER_CONTROL_CALLBACK function type is defined in the Wdm.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the PO_FX_POWER_CONTROL_CALLBACK function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for WDM Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Supported starting with Windows 8.
Target Platform	Desktop
Header	wdm.h (include Wudfwdm.h)
IRQL	Called at IRQL <= DISPATCH_LEVEL.