Vista Power Plan Integration
We hate GUIs. No, let me rephrase that - we really hate GUIs. It's not that we don't want to provide a nice pretty UI to our customers - it's just not what we do. More importantly, it's really not what we want to spend our time doing. We think driver devs should stick to drivers and GUI devs should stick to GUIs. Luckily Microsoft seems to agree.
We've Been Here Before...
You're probably quite familiar with the Power Management tab in Device Manager. You know, the one with the check boxes for enabling the suspend and/or wake options of a device? Figure 1 shows what it looks like if you're drawing a blank at the moment.
Figure 1 - Device Manager...Power Management Tab
|
If your device has one of these in Device Manager, then you already know the best thing about this dialog is that it's automatically generated for you. Just add a couple of pre-defined GUIDs to your WMI registration block and you're done. This rocks for a couple of reasons:
-
-
1. It provides a consistent UI to the users of the system. They control the sleep behavior of the mouse the same way they control the sleep behavior of the keyboard or USB toaster. This is a good thing.
-
There is no GUI code to write (*the crowd cheers*). Personally, I'd rather write some WMI code using WMILIB than try to write a property page.
On the other hand, this sucks for a couple of reasons:
-
-
"Allow this device to suspend" is a good generic option. But what if you want the user to configure what the timeout is for suspend? You'll still need to write your own GUI to augment the built-in one.
-
There are only two built-in power management options. If your device supports a rich set of power management features, you'll still need to write your own GUI.
Vista to the Rescue
With Vista Microsoft has taken the idea of auto-generated, device management GUIs to the next level. Before we can discuss that, we need to understand the model for managing power settings on Vista.
Here's the Plan...
New in Vista is the concept of Power Plans that are used to describe the power management behavior of your system. For example, your current power plan indicates when Windows should turn off power to the monitor or spin down the hard disk. While it's possible to create your own power plans, by default Vista ships with the following three plans:
-
-
Power Saver Plan - Sacrifices performance for power savings.
-
Balanced Plan - Provides the best balance between performance and power savings.
-
High Performance Plan - Sacrifices power savings for performance.
Each of these plans provides alternate settings for AC or DC power. This means by default there are a total of six possible power plans. To configure a plan, you simply need to go to the Power Control Panel applet and change the advanced settings, as shown in Figure 2.
Figure 2 - Configuring a Power Plan
|
Power Plan Integration
OK, so why the hell are we including an article on a Vista Control Panel applet in The NT Insider? Well, here's the big news - The NT Insider has been bought by MSDN Magazine! As an introductory article to our readers, this sidebar will discuss how to write Control Panel applets that conform to the Aero UI interface standard. This will lead us to a discussion on how to use XML Paper to make your Web apps rock and should serve as a nice setup for our next issue, which will explore VB forms and managed-ness. We hope you'll enjoy the new format, articles, and name - The CLR Insider!
Not!
Sorry, couldn't resist...The real reason this article made it into an issue of The NT Insider is Vista makes it a cinch to integrate your driver into the Power Plan GUI that is presented to the user. This feature allows your driver to expose a rich set of power management settings in a common location with all of the other standard power management settings. All that's required is a bit of INF magic and the addition of a call to PoRegisterPowerSettingCallback.
To demonstrate how to do some of this integration, we'll add our own custom group to the Power Plan dialog consisting of three selective suspend settings for our devices: Aggressive Suspend, Not So Aggressive Suspend, and No Suspend.
INF Stuff
A new AddPowerSetting directive has been added to the device install section (also known as DDInstall) of the INF file. Figure 3 shows an example of defining an AddPowerSetting section using the OSRUSBFX2 sample from the WDF distribution.
Figure 3 - Defining AddPowerSetting
|
Once you've named the section, you'll need to create it. The section you create will have four critical pieces that are discussed below.
1. A SubGroup value that defines a group of settings for your device. As shown in Figure 4, a SubGroup consists of a GUID, a name for your group of settings, and a description.
Figure 4 - Defining SubGroups
|
2. A Setting value that defines a particular setting that is configurable within this group. As shown in Figure 5, a Setting consists of a unique GUID, a name for the setting, and a description of the setting.
Figure 5 - Defining a Setting
|
3. Once you have a Setting defined, you need to follow it up with all the possible values for this setting. This is done using one or more Value entries, each of which has a zero based number to identify the entry, a name for the option, a description of the option, and some data associated with the option. The data, which can be whatever you like, is stored in the registry as the type specified. Note that you indicate the type using the same constants used in an AddReg section. For example, 0x001001 is REG_DWORD. An example Setting is shown in Figure 6.
Figure 6 - Defining Values for a Setting
|
4. Lastly, it is your job to pick reasonable defaults for the six built-in Power Plans. This is done by providing a Default value for each Power Plan and indicating which Value should be used for each, as shown Figure 7.
Figure 7 - Defining Defaluts for Built-in Power Plans
|
NOTE: If you had multiple settings for your device, you would simply create another Setting value with its own unique Values and Defaults.
The result of installing the INF described above is shown in Figure 8.
Figure 8 - You're Done!
|
Pretty slick, eh?
Getting Notified of Changes
Getting notified when this setting is changed is cake. All that's required is a call to PoRegisterPowerSettingCallback using the GUID from your Setting line, which can be seen in Figure 9.
|
//
// Register changes to our custom power policy setting
//
status = PoRegisterPowerSettingCallback(
WdfDeviceWdmGetDeviceObject(device),
&OSRFX2_SUSPEND_SETTING_GUID,
OsrFx2PowerSettingCallback,
pDevContext,
&pDevContext->PowerSettingCallbackHandle);
Figure 9 - Change Notification...Call PoRegisterPowerSettingCallback
|
Once you've made this call, the OsrFx2PowerSettingCallback (See Figure 10) will be called each time the user changes the setting for your device. You'll be passed a pointer to the GUID for the setting (so you can use the same callback for multiple setting GUIDs) and also the Value for the setting the user chose.
|
#define OSRFX2_AGGRESIVE_SUSPEND_SETTING 500
#define OSRFX2_NOT_SO_AGGRESIVE_SUSPEND_SETTING 600
#define OSRFX2_NEVER_SUSPEND_SETTING 700
NTSTATUS
OsrFx2PowerSettingCallback(
IN CONST LPGUID SettingGuid,
IN PVOID Value,
IN ULONG ValueLength,
IN PVOID Context
) {
ULONG setting;
//
// Is this the setting that we want?
// Note that we only currently register for one
// setting, so we should only get called with this
// one. But, we may add more later.
//
if (IsEqualGUID(&OSRFX2_SAMPLE_SETTING_GUID,
SettingGuid)) {
//
// Sanity check on the input
//
if (!Value ||
ValueLength != sizeof(ULONG)) {
return STATUS_INVALID_PARAMETER;
}
//
// Get the suspend mode that the user wants us in
//
setting = *(PULONG)Value;
switch (setting) {
case OSRFX2_AGGRESIVE_SUSPEND_SETTING: {
//
// Change to aggressive suspend
//
break;
}
case OSRFX2_NOT_SO_AGGRESIVE_SUSPEND_SETTING: {
//
// Change to not so aggressive suspend
//
break;
}
case OSRFX2_NEVER_SUSPEND_SETTING: {
//
// Change to never suspend
//
break;
}
default: {
//
// Shouldn't be here...
//
break;
}
}
return STATUS_SUCCESS;
}
return STATUS_INVALID_DEVICE_REQUEST;
}
Figure 10 - OsrFx2PowerSettingCallback
|
That's Just the Beginning
This article is just a taste of what you can do with the AddPowerSetting section of your INF. You will also be able to display your settings to the user in different ways, not just as discrete values (e.g. imagine having a "% Brightness" option). For more info we highly suggest you check out the presentations here at WinHEC on Vista power management and keep an eye out for updated documentation in the WDK.
Post Your Comment
