Search
Module:
Directory

   Desktop Functions:

   Smart Device Functions:


Show Recent Changes
Subscribe (RSS)
Misc. Pages
Comments
FAQ
Helpful Tools
Playground
Suggested Reading
Website TODO List
Download Visual Studio Add-In

SYSTEM_POWER_POLICY (powrprof)
 
.
Summary
TODO - a short description

C# Signature:

  enum POWER_ACTION : uint
  {
    PowerActionNone = 0,       // No system power action.
    PowerActionReserved,       // Reserved; do not use.
    PowerActionSleep,      // Sleep.
    PowerActionHibernate,      // Hibernate.
    PowerActionShutdown,       // Shutdown.
    PowerActionShutdownReset,  // Shutdown and reset.
    PowerActionShutdownOff,    // Shutdown and power off.
    PowerActionWarmEject,      // Warm eject.
  }

  [Flags]
  enum PowerActionFlags : uint
  {
    POWER_ACTION_QUERY_ALLOWED = 0x00000001, // Broadcasts a PBT_APMQUERYSUSPEND event to each application to request permission to suspend operation.
    POWER_ACTION_UI_ALLOWED = 0x00000002, // Applications can prompt the user for directions on how to prepare for suspension. Sets bit 0 in the Flags parameter passed in the lParam parameter of
    WM_POWERBROADCAST.
    POWER_ACTION_OVERRIDE_APPS = 0x00000004, // Ignores applications that do not respond to the PBT_APMQUERYSUSPEND event broadcast in the WM_POWERBROADCAST message.
    POWER_ACTION_LIGHTEST_FIRST = 0x10000000, // Uses the first lightest available sleep state.
    POWER_ACTION_LOCK_CONSOLE = 0x20000000, // Requires entry of the system password upon resume from one of the system standby states.
    POWER_ACTION_DISABLE_WAKES = 0x40000000, // Disables all wake events.
    POWER_ACTION_CRITICAL = 0x80000000, // Forces a critical suspension.
  }

  [Flags]
  enum PowerActionEventCode : uint
  {
    POWER_LEVEL_USER_NOTIFY_TEXT = 0x00000001, // User notified using the UI.
    POWER_LEVEL_USER_NOTIFY_SOUND = 0x00000002, // User notified using sound.
    POWER_LEVEL_USER_NOTIFY_EXEC = 0x00000004, // Specifies a program to be executed.
    POWER_USER_NOTIFY_BUTTON = 0x00000008, // Indicates that the power action is in response to a user power button press.
    POWER_USER_NOTIFY_SHUTDOWN = 0x00000010, // Indicates a power action of shutdown/off.
    POWER_FORCE_TRIGGER_RESET = 0x80000000, // Clears a user power button press.
  }

  enum SYSTEM_POWER_STATE : UInt32
  {
    PowerSystemUnspecified = 0,
    PowerSystemWorking = 1,
    PowerSystemSleeping1 = 2,
    PowerSystemSleeping2 = 3,
    PowerSystemSleeping3 = 4,
    PowerSystemHibernate = 5,
    PowerSystemShutdown = 6,
    PowerSystemMaximum = 7
  }

  [StructLayout(LayoutKind.Sequential, Pack = 4)]
  struct POWER_ACTION_POLICY
  {
    public POWER_ACTION Action;
    public PowerActionFlags Flags;
    public PowerActionEventCode EventCode;
  }

  [StructLayout(LayoutKind.Sequential, Pack = 4)]
  struct SYSTEM_POWER_LEVEL // SIZE MUST BE 24 bytes
  {
    public byte Enable;
    [MarshalAs(UnmanagedType.ByValArray, SizeConst = 2)]
    public byte[] Spare;
    public uint BatteryLevel;
    public POWER_ACTION_POLICY PowerPolicy;
    public SYSTEM_POWER_STATE MinSystemState;
  }

  [StructLayout(LayoutKind.Sequential, Pack = 4)]
  struct SYSTEM_POWER_POLICY // SIZE MUST BE 232 bytes
  {
    public UInt32 Revision;
    public POWER_ACTION_POLICY PowerButton;
    public POWER_ACTION_POLICY SleepButton;
    public POWER_ACTION_POLICY LidClose;
    public SYSTEM_POWER_STATE LidOpenWake;
    public UInt32 Reserved;
    public POWER_ACTION_POLICY Idle;
    public UInt32 IdleTimeout;
    public byte IdleSensitivity;
    public byte DynamicThrottle;
    [MarshalAs(UnmanagedType.ByValArray, SizeConst = 2)]
    public byte[] Spare2;
    public SYSTEM_POWER_STATE MinSleep;
    public SYSTEM_POWER_STATE MaxSleep;
    public SYSTEM_POWER_STATE ReducedLatencySleep;
    public UInt32 WinLogonFlags;
    public UInt32 Spare3;
    public UInt32 DozeS4Timeout;
    public UInt32 BroadcastCapacityResolution;
    [MarshalAs(UnmanagedType.ByValArray, SizeConst = 4)]
    public SYSTEM_POWER_LEVEL[] DischargePolicy;
    public UInt32 VideoTimeout;
    public byte VideoDimDisplay;
    [MarshalAs(UnmanagedType.ByValArray, SizeConst = 3)]
    public UInt32[] VideoReserved;
    public UInt32 SpindownTimeout;
    public byte OptimizeForPower;
    public byte FanThrottleTolerance;
    public byte ForcedThrottle;
    public byte MinThrottle;
    public POWER_ACTION_POLICY OverThrottled;
  }

VB Signature:

Declare Function SYSTEM_POWER_POLICY Lib "powrprof.dll" (TODO) As TODO

User-Defined Types:

None.

Alternative Managed API:

Do you know one? Please contribute it!

Notes:

Please make sure that the size of SYSTEM_POWER_LEVEL is 24 bytes (Marshal.SizeOf(typeof(SYSTEM_POWER_LEVEL))) and the size of SYSTEM_POWER_POLICY (Marshal.SizeOf(typeof(SYSTEM_POWER_POLICY))) is 232 bytes. If the size is off, CallNtPowerInformation will return STATUS_INVALID_PARAMETER (0xC000000D).

Tips & Tricks:

Please add some!

Sample Code:

class changePowerSettings
{
  const uint STATUS_SUCCESS = 0;

  /// <summary>
  /// Indicates the specific power information to be set or retrieved. It used as a parameter in CallNtPowerInformation function.
  /// </summary>
  public enum POWER_INFORMATION_LEVEL : Int32
  {
    /// <summary>
    /// <para> The lpInBuffer parameter must be NULL; otherwise, the function returns ERROR_INVALID_PARAMETER.</para>
    ///The lpOutputBuffer buffer receives a ULONGLONG that specifies the interrupt-time count, in 100-nanosecond units, at the last system sleep time.
    /// </summary>
    LastSleepTime = 15,
    /// <summary>
    /// <para> The lpInBuffer parameter must be NULL; otherwise, the function returns ERROR_INVALID_PARAMETER.</para>
    /// The lpOutputBuffer buffer receives a ULONGLONG that specifies the interrupt-time count, in 100-nanosecond units, at the last system wake time.
    /// </summary>
    LastWakeTime = 14,
    /// <summary>
    /// <para> The lpInBuffer parameter must be NULL; otherwise the function returns ERROR_INVALID_PARAMETER.</para>
    /// 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.
    /// </summary>
    ProcessorInformation = 11,
    /// <summary>
    /// <para> The lpInBuffer parameter must be NULL; otherwise, the function returns ERROR_INVALID_PARAMETER.</para>
    /// The lpOutputBuffer buffer receives a SYSTEM_BATTERY_STATE structure containing information about the current system battery.
    /// </summary>
    SystemBatteryState = 5,
    /// <summary>
    /// <para> The lpInBuffer parameter must be NULL; otherwise the function returns ERROR_INVALID_PARAMETER.</para>
    /// The lpOutputBuffer buffer receives a ULONG value containing the system execution state buffer.
    /// <para> This value may contain any combination of the following values: ES_SYSTEM_REQUIRED, ES_DISPLAY_REQUIRED, or ES_USER_PRESENT.</para>
    /// For more information, see the SetThreadExecutionState function.
    /// </summary>
    SystemExecutionState = 16,
    /// <summary>
    /// <para> The lpInBuffer parameter must be NULL, otherwise, the function returns ERROR_INVALID_PARAMETER.</para>
    /// The lpOutputBuffer buffer receives a SYSTEM_POWER_CAPABILITIES structure containing the current system power capabilities.
    /// <para> 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.</para>
    /// </summary>
    SystemPowerCapabilities = 4,
    /// <summary>
    /// <para> The lpInBuffer parameter must be NULL; otherwise, the function returns ERROR_INVALID_PARAMETER.</para>
    /// The lpOutputBuffer buffer receives a SYSTEM_POWER_INFORMATION structure.
    /// <para> Applications can use this level to retrieve information about the idleness of the system.</para>
    /// </summary>
    SystemPowerInformation = 12,
    /// <summary>
    /// <para> 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.</para>
    /// 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.
    /// </summary>
    SystemPowerPolicyAc = 0,
    /// <summary>
    /// <para> The lpInBuffer parameter must be NULL; otherwise, the function returns ERROR_INVALID_PARAMETER.</para>
    /// 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.
    /// </summary>
    SystemPowerPolicyCurrent = 8,
    /// <summary>
    /// <para> 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.</para>
    /// The lpOutputBuffer buffer receives a SYSTEM_POWER_POLICY structure containing the current system power policy used while the system is running on battery power.
    /// </summary>
    SystemPowerPolicyDc = 1,
    /// <summary>
    /// <para> 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.</para>
    /// 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.
    /// </summary>
    SystemReserveHiberFile = 10
  }

  enum POWER_ACTION : uint
  {
    PowerActionNone = 0,       // No system power action.
    PowerActionReserved,       // Reserved; do not use.
    PowerActionSleep,      // Sleep.
    PowerActionHibernate,      // Hibernate.
    PowerActionShutdown,       // Shutdown.
    PowerActionShutdownReset,  // Shutdown and reset.
    PowerActionShutdownOff,    // Shutdown and power off.
    PowerActionWarmEject,      // Warm eject.
  }

  [Flags]
  enum PowerActionFlags : uint
  {
    POWER_ACTION_QUERY_ALLOWED = 0x00000001, // Broadcasts a PBT_APMQUERYSUSPEND event to each application to request permission to suspend operation.
    POWER_ACTION_UI_ALLOWED = 0x00000002, // Applications can prompt the user for directions on how to prepare for suspension. Sets bit 0 in the Flags parameter passed in the lParam parameter of WM_POWERBROADCAST.
    POWER_ACTION_OVERRIDE_APPS = 0x00000004, // Ignores applications that do not respond to the PBT_APMQUERYSUSPEND event broadcast in the WM_POWERBROADCAST message.
    POWER_ACTION_LIGHTEST_FIRST = 0x10000000, // Uses the first lightest available sleep state.
    POWER_ACTION_LOCK_CONSOLE = 0x20000000, // Requires entry of the system password upon resume from one of the system standby states.
    POWER_ACTION_DISABLE_WAKES = 0x40000000, // Disables all wake events.
    POWER_ACTION_CRITICAL = 0x80000000, // Forces a critical suspension.
  }

  [Flags]
  enum PowerActionEventCode : uint
  {
    POWER_LEVEL_USER_NOTIFY_TEXT = 0x00000001, // User notified using the UI.
    POWER_LEVEL_USER_NOTIFY_SOUND = 0x00000002, // User notified using sound.
    POWER_LEVEL_USER_NOTIFY_EXEC = 0x00000004, // Specifies a program to be executed.
    POWER_USER_NOTIFY_BUTTON = 0x00000008, // Indicates that the power action is in response to a user power button press.
    POWER_USER_NOTIFY_SHUTDOWN = 0x00000010, // Indicates a power action of shutdown/off.
    POWER_FORCE_TRIGGER_RESET = 0x80000000, // Clears a user power button press.
  }

  enum SYSTEM_POWER_STATE : UInt32
  {
    PowerSystemUnspecified = 0,
    PowerSystemWorking = 1,
    PowerSystemSleeping1 = 2,
    PowerSystemSleeping2 = 3,
    PowerSystemSleeping3 = 4,
    PowerSystemHibernate = 5,
    PowerSystemShutdown = 6,
    PowerSystemMaximum = 7
  }

  [StructLayout(LayoutKind.Sequential, Pack = 4)]
  struct POWER_ACTION_POLICY
  {
    public POWER_ACTION Action;
    public PowerActionFlags Flags;
    public PowerActionEventCode EventCode;
  }

  [StructLayout(LayoutKind.Sequential, Pack = 4)]
  struct SYSTEM_POWER_LEVEL // SIZE MUST BE 24 bytes
  {
    public byte Enable;
    [MarshalAs(UnmanagedType.ByValArray, SizeConst = 2)]
    public byte[] Spare;
    public uint BatteryLevel;
    public POWER_ACTION_POLICY PowerPolicy;
    public SYSTEM_POWER_STATE MinSystemState;
  }

  [StructLayout(LayoutKind.Sequential, Pack = 4)]
  struct SYSTEM_POWER_POLICY // SIZE MUST BE 232 bytes
  {
    public UInt32 Revision;
    public POWER_ACTION_POLICY PowerButton;
    public POWER_ACTION_POLICY SleepButton;
    public POWER_ACTION_POLICY LidClose;
    public SYSTEM_POWER_STATE LidOpenWake;
    public UInt32 Reserved;
    public POWER_ACTION_POLICY Idle;
    public UInt32 IdleTimeout;
    public byte IdleSensitivity;
    public byte DynamicThrottle;
    [MarshalAs(UnmanagedType.ByValArray, SizeConst = 2)]
    public byte[] Spare2;
    public SYSTEM_POWER_STATE MinSleep;
    public SYSTEM_POWER_STATE MaxSleep;
    public SYSTEM_POWER_STATE ReducedLatencySleep;
    public UInt32 WinLogonFlags;
    public UInt32 Spare3;
    public UInt32 DozeS4Timeout;
    public UInt32 BroadcastCapacityResolution;
    [MarshalAs(UnmanagedType.ByValArray, SizeConst = 4)]
    public SYSTEM_POWER_LEVEL[] DischargePolicy;
    public UInt32 VideoTimeout;
    public byte VideoDimDisplay;
    [MarshalAs(UnmanagedType.ByValArray, SizeConst = 3)]
    public UInt32[] VideoReserved;
    public UInt32 SpindownTimeout;
    public byte OptimizeForPower;
    public byte FanThrottleTolerance;
    public byte ForcedThrottle;
    public byte MinThrottle;
    public POWER_ACTION_POLICY OverThrottled;
  }

  [DllImport("powrprof.dll")]
  static extern uint CallNtPowerInformation(
     int InformationLevel,
     [In] SYSTEM_POWER_POLICY[] lpInputBuffer,
     int nInputBufferSize,
     [Out] SYSTEM_POWER_POLICY[] lpOutputBuffer,
     int nOutputBufferSize
  );

  public changePowerSettings()
  {
    SYSTEM_POWER_POLICY[] powerInfo = new SYSTEM_POWER_POLICY[1];
    int splSize = Marshal.SizeOf(typeof(SYSTEM_POWER_LEVEL));
    int structureSize = Marshal.SizeOf(typeof(SYSTEM_POWER_POLICY));
    uint retval = CallNtPowerInformation(
    (int)POWER_INFORMATION_LEVEL.SystemPowerPolicyAc,
    null,
    0,
    powerInfo,
    structureSize
    );
    if (retval == STATUS_SUCCESS)
    {
      // do something
    }
  }
}

Documentation

Please edit this page!

Do you have...

  • helpful tips or sample code to share for using this API in managed code?
  • corrections to the existing content?
  • variations of the signature you want to share?
  • additional languages you want to include?

Select "Edit This Page" on the right hand toolbar and edit it! Or add new pages containing supporting types needed for this API (structures, delegates, and more).

 
Access PInvoke.net directly from VS:
Terms of Use
Find References
Show Printable Version
Revisions