CallNtPowerInformation function (powerbase.h)

Sets or retrieves power information.

Syntax

NTSTATUS CallNtPowerInformation(
  [in]  POWER_INFORMATION_LEVEL InformationLevel,
  [in]  PVOID                   InputBuffer,
  [in]  ULONG                   InputBufferLength,
  [out] PVOID                   OutputBuffer,
  [in]  ULONG                   OutputBufferLength
);

Parameters

[in] InformationLevel

The information level requested. This value indicates the specific power information to be set or retrieved. This parameter must be one of the following POWER_INFORMATION_LEVEL enumeration type values.

Value Meaning
AdministratorPowerPolicy
9
This information level is not supported.
LastSleepTime
15
The lpInBuffer parameter must be NULL; otherwise, the function returns ERROR_INVALID_PARAMETER.

The lpOutputBuffer buffer receives a ULONGLONG that specifies the interrupt-time count, in 100-nanosecond units, at the last system sleep time.

LastWakeTime
14
The lpInBuffer parameter must be NULL; otherwise, the function returns ERROR_INVALID_PARAMETER.

The lpOutputBuffer buffer receives a ULONGLONG that specifies the interrupt-time count, in 100-nanosecond units, at the last system wake time.

ProcessorInformation
11
The lpInBuffer parameter must be NULL; otherwise the function returns ERROR_INVALID_PARAMETER.

The lpOutputBuffer buffer receives one PROCESSOR_POWER_INFORMATION structure for each processor that is installed on the system. Use the GetSystemInfo function to retrieve the number of processors.

ProcessorPowerPolicyAc
18
This information level is not supported.
ProcessorPowerPolicyCurrent
22
This information level is not supported.
ProcessorPowerPolicyDc
19
This information level is not supported.
SystemBatteryState
5
The lpInBuffer parameter must be NULL; otherwise, the function returns ERROR_INVALID_PARAMETER.

The lpOutputBuffer buffer receives a SYSTEM_BATTERY_STATE structure containing information about the current system battery.

SystemExecutionState
16
The lpInBuffer parameter must be NULL; otherwise the function returns ERROR_INVALID_PARAMETER.

The lpOutputBuffer buffer receives a ULONG value containing the system execution state buffer. This value may contain any combination of the following values: ES_SYSTEM_REQUIRED, ES_DISPLAY_REQUIRED, or ES_USER_PRESENT. For more information, see the SetThreadExecutionState function.

SystemPowerCapabilities
4
The lpInBuffer parameter must be NULL, otherwise, the function returns ERROR_INVALID_PARAMETER.

The lpOutputBuffer buffer receives a SYSTEM_POWER_CAPABILITIES structure containing the current system power capabilities.

This information represents the currently supported power capabilities. It may change as drivers are installed in the system. For example, installation of legacy device drivers that do not support power management disables all system sleep states.

SystemPowerInformation
12
The lpInBuffer parameter must be NULL; otherwise, the function returns ERROR_INVALID_PARAMETER.

The lpOutputBuffer buffer receives a SYSTEM_POWER_INFORMATION structure.

Applications can use this level to retrieve information about the idleness of the system.

SystemPowerPolicyAc
0
If lpInBuffer is not NULL, the function applies the SYSTEM_POWER_POLICY values passed in lpInBuffer to the current system power policy used while the system is running on AC (utility) power.

The lpOutputBuffer buffer receives a SYSTEM_POWER_POLICY structure containing the current system power policy used while the system is running on AC (utility) power.

SystemPowerPolicyCurrent
8
The lpInBuffer parameter must be NULL; otherwise, the function returns ERROR_INVALID_PARAMETER.

The lpOutputBuffer buffer receives a SYSTEM_POWER_POLICY structure containing the current system power policy used while the system is running on AC (utility) power.

SystemPowerPolicyDc
1
If lpInBuffer is not NULL, the function applies the SYSTEM_POWER_POLICY values passed in lpInBuffer to the current system power policy used while the system is running on battery power.

The lpOutputBuffer buffer receives a SYSTEM_POWER_POLICY structure containing the current system power policy used while the system is running on battery power.

SystemReserveHiberFile
10
If lpInBuffer is not NULL and the current user has sufficient privileges, the function commits or decommits the storage required to hold the hibernation image on the boot volume.

The lpInBuffer parameter must point to a BOOLEAN value indicating the desired request. If the value is TRUE, the hibernation file is reserved; if the value is FALSE, the hibernation file is removed.

VerifyProcessorPowerPolicyAc
20
This information level is not supported.
VerifyProcessorPowerPolicyDc
21
This information level is not supported.
VerifySystemPolicyAc
2
This information level is not supported.
VerifySystemPolicyDc
3
This information level is not supported.

[in] InputBuffer

A pointer to an optional input buffer. The data type of this buffer depends on the information level requested in the InformationLevel parameter.

[in] InputBufferLength

The size of the input buffer, in bytes.

[out] OutputBuffer

A pointer to an optional output buffer. The data type of this buffer depends on the information level requested in the InformationLevel parameter. If the buffer is too small to contain the information, the function returns STATUS_BUFFER_TOO_SMALL.

[in] OutputBufferLength

The size of the output buffer, in bytes. Depending on the information level requested, this may be a variably sized buffer.

Return value

If the function succeeds, the return value is STATUS_SUCCESS.

If the function fails, the return value can be one the following status codes.

Status Meaning
STATUS_BUFFER_TOO_SMALL
The output buffer is of insufficient size to contain the data to be returned.
STATUS_ACCESS_DENIED
The caller had insufficient access rights to perform the requested action.

Remarks

Changes made to the current system power policy using CallNtPowerInformation are immediate, but they are not persistent; that is, the changes are not stored as part of a power scheme. Any changes to system power policy made with CallNtPowerInformation may be overwritten by changes to a policy scheme made by the user in the Power Options control panel program, or by subsequent calls to WritePwrScheme, SetActivePwrScheme, or other power scheme functions.

For more information on using PowrProf.h, see Power Schemes.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header powerbase.h
Library PowrProf.lib
DLL PowrProf.dll

See also

ADMINISTRATOR_POWER_POLICY

PROCESSOR_POWER_INFORMATION

PROCESSOR_POWER_POLICY

Power Management Functions

SYSTEM_BATTERY_STATE structure

SYSTEM_POWER_CAPABILITIES

SYSTEM_POWER_INFORMATION

SYSTEM_POWER_POLICY