PoCreatePowerRequest function (ntifs.h)

Article
07/06/2023

The PoCreatePowerRequest routine creates a power request object.

Syntax

NTSTATUS PoCreatePowerRequest(
  [out] PVOID                   *PowerRequest,
  [in]  PDEVICE_OBJECT          DeviceObject,
  [in]  PCOUNTED_REASON_CONTEXT Context
);

Parameters

[out] PowerRequest

A pointer to a location into which the routine writes a pointer to the newly created power request object. If the call fails, the routine writes NULL to this location.

[in] DeviceObject

A pointer to the device object of the caller (a DEVICE_OBJECT structure).

[in] Context

A pointer to a COUNTED_REASON_CONTEXT structure that describes why the caller is creating the power request object. This parameter is optional and can be set to NULL.

Return value

PoCreatePowerRequest returns STATUS_SUCCESS if the call is successful. If the call fails, possible error return codes include the following:

Return code	Description
STATUS_INVALID_PARAMETER	The DeviceObject parameter is NULL.
STATUS_INSUFFICIENT_RESOURCES	There is not enough memory available to create a power request object.

Remarks

This routine creates a power request object. To enable power requests, the caller should create one power request object and use that object for all calls to the PoSetPowerRequest and PoClearPowerRequest routines.

A driver can use power requests to override certain aspects of the computer's default power behavior. For example, a driver for a TV receiver device can use power requests to prevent the power manager from automatically blanking the display during extended periods of time in which no user interaction occurs.

When the power request object is no longer needed, the caller must delete the object by calling the PoDeletePowerRequest routine. The driver must delete the power request object before it deletes the device object that was used to create the power request object.

Requirements

Requirement	Value
Minimum supported client	Windows 7
Target Platform	Universal
Header	ntifs.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL