Expand Minimize

CallNtPowerInformation function

Sets or retrieves power information.

Syntax


NTSTATUS WINAPI CallNtPowerInformation(
  _In_   POWER_INFORMATION_LEVEL InformationLevel,
  _In_   PVOID lpInputBuffer,
  _In_   ULONG nInputBufferSize,
  _Out_  PVOID lpOutputBuffer,
  _In_   ULONG nOutputBufferSize
);

Parameters

InformationLevel [in]

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.

ValueMeaning
AdministratorPowerPolicy
9

This information level is not supported.

Windows Server 2003 and Windows XP:  If lpInBuffer is not NULL and the current user has administrator privileges, the function applies the ADMINISTRATOR_POWER_POLICY passed in lpInBuffer to the system.

The lpOutputBuffer buffer receives the current system ADMINISTRATOR_POWER_POLICY structure.

Applications can use this level to optionally set or retrieve the current administrator overrides. The caller must have administrator rights to apply an administrator override; otherwise, the function returns STATUS_ACCESS_DENIED.

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.

Windows Server 2003 and Windows XP:  The lpInBuffer parameter must be NULL, otherwise, the function returns ERROR_INVALID_PARAMETER.

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

ProcessorPowerPolicyCurrent
22

This information level is not supported.

Windows Server 2003 and Windows XP:  The lpInBuffer parameter must be NULL; otherwise, the function returns ERROR_INVALID_PARAMETER.

The lpOutputBuffer buffer receives a PROCESSOR_POWER_POLICY structure containing the current system processor power policy in use.

ProcessorPowerPolicyDc
19

This information level is not supported.

Windows Server 2003 and Windows XP:  The lpInBuffer parameter must be NULL; otherwise, the function returns ERROR_INVALID_PARAMETER.

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

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.

Windows Server 2003 and Windows XP:  If lpInBuffer and lpOutputBuffer are not NULL, the function copies the PROCESSOR_POWER_POLICY structure passed in lpInBuffer to lpOutputBuffer and updates it to represent processor capabilities and other requirements while the system is running on AC power. If the input policy has some setting which cannot be updated, an error occurs.

VerifyProcessorPowerPolicyDc
21

This information level is not supported.

Windows Server 2003 and Windows XP:  If lpInBuffer and lpOutputBuffer are not NULL, the function copies the PROCESSOR_POWER_POLICY structure passed in lpInBuffer to lpOutputBuffer and updates it to represent processor capabilities and other requirements while the system is running on battery power. If the input policy has some setting that cannot be updated, an error occurs.

VerifySystemPolicyAc
2

This information level is not supported.

Windows Server 2003 and Windows XP:  If lpInBuffer and lpOutputBuffer are not NULL, the function copies the SYSTEM_POWER_POLICY structure passed in lpInBuffer to lpOutputBuffer and updates it to represent system capabilities and other requirements while the system is running on AC power. If the input policy has some setting that cannot be updated, an error occurs.

Applications can use this level to verify all power action policy settings, and update all system states to match what is supported by the platform. If an administrator override exists, it is applied to the SYSTEM_POWER_POLICY structure returned in lpOutputBuffer.

VerifySystemPolicyDc
3

This information level is not supported.

Windows Server 2003 and Windows XP:  If lpInBuffer and lpOutputBuffer are not NULL, the function copies the SYSTEM_POWER_POLICY structure passed in lpInBuffer to lpOutputBuffer and updates it to represent system capabilities and other requirements while the system is running on battery power. If the input policy has some setting that cannot be updated, an error occurs.

Applications can use this level to verify all power action policy settings, and update all system states to match what is supported by the platform. If an administrator override exists, it is applied to the SYSTEM_POWER_POLICY structure returned in lpOutputBuffer.

 

lpInputBuffer [in]

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

nInputBufferSize [in]

The size of the input buffer, in bytes.

lpOutputBuffer [out]

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.

nOutputBufferSize [in]

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.

StatusMeaning
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

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Powerbase.h;
PowrProf.h on Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003, and Windows XP

Library

PowrProf.lib

DLL

PowrProf.dll

See also

Power Management Functions
ADMINISTRATOR_POWER_POLICY
PROCESSOR_POWER_INFORMATION
PROCESSOR_POWER_POLICY
SYSTEM_BATTERY_STATE
SYSTEM_POWER_CAPABILITIES
SYSTEM_POWER_INFORMATION
SYSTEM_POWER_POLICY

 

 

Community Additions

ADD
Show:
© 2014 Microsoft