Working in the Background : PROVIDING POWER MANAGEMENT (part 1) - Getting the Power Management State

The entire computer industry is under significant pressure to become greener, to use less power, and to use power more efficiently. Microsoft has continued to address this need by updating the power management features in every version of Windows.

Like many parts of Windows, power management works in the background by monitoring the system in various ways. Applications can interact with power management functionality in a number of ways. The most common interaction is to query power management about the current configuration, so that the application knows how to run in a low-power environment, such as a laptop. An application can also subscribe to power management events to discover when certain events occur, such as a low-battery alarm. The Power Management example shows how to perform basic power management monitoring.

1. Configuring the Power Management Example

This example begins with a Windows Forms application. You'll need to add a button (btnGet) to obtain data about the current power management functionality and a list box (lstData) to output the results of the query. In addition, you'll need to add a reference to Microsoft.WindowsAPICodePack.DLL and provide the following using statement:

using Microsoft.WindowsAPICodePack.ApplicationServices;

2. Getting the Power Management State

It used to be difficult to get a substantial amount of information from Windows regarding the status of the power management system. An application could start to perform a long task when battery power was low, resulting in lost data, corruption, or other problems in at least a few cases when the battery suddenly decided to fail. Windows 7 makes it possible to monitor the power state so that your application can interact with the host system appropriately. For example, it's now possible to anticipate a low-battery state and to reserve disk operations to those that are essential to data protection, rather than use the disk as normal. Listing 1 shows the incredible amount of information you can now obtain from Windows 7.

Example 1. Outputting the power management state

private void btnGet_Click(object sender, EventArgs e)
{
    // Clear any existing data.
    lstData.Items.Clear();

    // Obtain the current power source.
    lstData.Items.Add("Power Source: " + PowerManager.PowerSource);

    // Check for a battery.
    if (PowerManager.IsBatteryPresent)
    {
        // Display a battery present message.
        lstData.Items.Add("Battery Present");

        // Get the battery state.
        BatteryState BattState = PowerManager.GetCurrentBatteryState();

        // Display the battery statistics.
        lstData.Items.Add("\tBattery Life %: " +
            PowerManager.BatteryLifePercent);
        lstData.Items.Add("\tBattery Life (mw): " +
            BattState.CurrentCharge);
        lstData.Items.Add("\tMaximum Charge (mw): " +
            BattState.MaxCharge);
        lstData.Items.Add("\tShort Term Battery? " +
            PowerManager.IsBatteryShortTerm);
        lstData.Items.Add("\tSuggested Battery Warning Charge (mw): " +
            BattState.SuggestedBatteryWarningCharge);
        lstData.Items.Add("\tSuggested Battery Critical Charge (mw): " +
            BattState.SuggestedCriticalBatteryCharge);

        // Check the current battery usage.
        if (BattState.ACOnline)
            lstData.Items.Add("\tAC Online");
        else
        {
            lstData.Items.Add("\tSystem Using Battery");
            lstData.Items.Add("\t\tDischarge Rate: " +
                BattState.DischargeRate);
            lstData.Items.Add("\t\tEstimated Time Remaining: " +
                BattState.EstimatedTimeRemaining);
        }
    }

					  

// Display the monitor information.
    lstData.Items.Add("Monitor On? " + PowerManager.IsMonitorOn);
    lstData.Items.Add("Monitor Required? " +
        PowerManager.MonitorRequired);

    // Display the UPS status.
    lstData.Items.Add("UPS Attached? " +
        PowerManager.IsUpsPresent);

    // Display the current power personality.
    lstData.Items.Add("Current Power Personality: " +
        PowerManager.PowerPersonality);

    // Display an indicator that shows if the system will
    // block the sleep state.
    lstData.Items.Add("Will System Block Sleep State? " +
        PowerManager.RequestBlockSleep);
}

The example begins by checking the current power source using PowerManager.PowerSource. You'll normally see one of three values as output: AC, UPS, or Battery. The PowerManager class is static, so you don't have to create any objects to use it, as shown in the listing.

Theoretically, you can query any PowerManager property or method any time you want. However, some properties and methods make sense only at specific times. The next section of code works with the battery. It begins by checking the battery state using PowerManager.IsBatteryPresent. If the battery is present, the code begins checking the battery status.

The PowerManager class provides direct access to some battery information, such as whether the battery is present. You can also determine the percentage of battery life left, using the PowerManager.BatteryLifePercent property. However, to get the maximum amount of information, you must create a BatteryState object, which is BattState in this example. The information you can receive about the battery is much improved from previous versions of Windows. For example, you can now query the precise amount of battery life left in milliwatts (mw) by accessing the CurrentCharge property.

A special property, IsBatteryShortTerm, tells you whether the battery lasts a short time. This particular property is extremely useful in determining just how much you should depend on the battery to fuel your application. It's even possible to determine how fast the battery is being used by querying the DischargeRate property, and Windows will estimate how much time the battery has left when you access the EstimatedTimeRemaining property. In short, there's no longer any good reason for your application to run out of power, because Windows 7 provides you with great statistics for monitoring battery life.

The remaining PowerManager statistics fill in gaps from earlier versions of Windows. The PowerManager.IsMonitorOn property tells you whether the monitor is currently on, while the PowerManager.MonitorRequired tells you whether the system actually requires a monitor (it could be in a closet somewhere and not even have a monitor attached).

There are actually two places with a use for Windows 7 battery information. The first is a laptop battery. The second is an Uninterruptible Power Supply (UPS). You can determine whether a UPS is attached by using the PowerManager.IsUpsPresent property. One caveat for Windows 7 is that if your UPS relies on a serial cable, all you can determine is whether the UPS is attached. You need a newer UPS that has a USB cable to determine the UPS battery statistics.

The output of the PowerManager.PowerPersonality is a little confusing. If you have your system set for the Balanced option in the Power Options applet, the output says Automatic. There isn't any output for a custom setup. However, you can determine whether the system is using the Power Saver or High Performance option. Except for the plan name, there doesn't appear to be any way to obtain the settings for the power plan using the PowerManager class.

Figure 1. The Windows 7 power management features provide a lot of information.

Most of the PowerManager properties are read-only. The PowerManager.RequestBlockSleep property is read/write. When set to true, it blocks requests for the system to go into sleep mode. You can use this setting when the system needs to perform a long task that doesn't require user intervention. The default setting doesn't block sleep requests. It's important that you not use this setting on a laptop running on the battery. Using this setting could cause data loss when the laptop battery runs out of power, and the current system state isn't saved to the hard drive in the HiberFil.SYS file. Figure 1 shows typical output from this application for a desktop machine.