Working today to debug a problem with Granola that had been reported by a couple of different users, I got the opportunity yet again to get down and dirty with Windows XP power management.aspx#pmfunctionsxpandearlier). Windows APIs in general can range from robust and well-documented to quirky and confusing. Power management definitely falls into the latter category. It is a less-used API, which means that there are few forums online discussing anything but the most straightforward uses. Add to that the fact that most of the functionality was brand new in XP and was completely rewritten for Vista and you have a set of functions that can be difficult to use and understand, top to bottom. It’s almost as if Microsoft never intended for this API to be used.

The problem I tackled today (and attempted to tackle several other times this week) seemed straightforward: some users were reporting that running Granola disabled or made erratic their screensaver coming on, monitor powering down, and computer going to sleep. My first thought was that Granola wasn’t updating the internal view of the power scheme as the user changed it, but no, that worked fine. My second thought was that perhaps the I/O of logging and communicating over named pipes was causing the machine to stay awake, but that wasn’t it either. I tried one thing after another, only to be shut down again and again.

Windows uses a fairly sophisticated set of criteria.aspx) for determining an appropriate time to put the monitor and system to sleep. According to the documentation, “[a]s long as the system determines that there is user or application activity, it will not enter sleep.” That encompasses the obvious: user interaction is keyboard and mouse activity, application activity is processor utilization, memory activity, or I/O such as network activity. I checked all of these things in turn, only to find that none of them applied. I was obviously not touching the mouse or keyboard; the application itself uses almost no processor, memory, disk, or network. So what was going on?

I’ll cut the story short here. Calls to the power management API were being considered user interaction. The issue causing my confusion was actually twofold: first, these sleep criteria are not really as clear as they seem; second, the power management API was never really intended to be used like Granola uses it. I’ll speak to the first issue later, but as to the second, clearly the developers of Windows XP thought that only users would be changing the power settings. How they thought the user could be changing them without using the keyboard or mouse is an even more interesting question; perhaps these settings are intrinsically linked to the same structures that monitor user interaction with the console.

Finally, I’d reached the end of the road. I uploaded a new version of the software that eliminated the power management functionality and indeed the monitor shut down. I waited 2 minutes more for the system to sleep, but no luck. I continued to wait, and the system never slept. Exit the application, and the system sleeps. Start it up again and the system becomes the computer version of New York. Oh noes! Not again!!

To cut the story short again: the system would not sleep while running unvetted software. “Unvetted software” in this instance meant software that hadn’t been installed by the Windows installer. In Windows XP and later versions of Windows, running software that wasn’t put on the system by an installer produces a UI alert asking the user if it is OK to run the software even if the software was signed by a valid signature. Allowing the software to run apparently puts the system into such a state that it cannot sleep, even though it CAN power down the monitor. This is well outside of the documented interface.

And this is the murkiness of the criteria that I was speaking of earlier. Again, “[a]s long as the system determines that there is user or application activity, it will not enter sleep.” HOW the system determines this is what is unclear. With a closed-source system like Windows, this statement isn’t really helpful from an API-specification standpoint. It may as well say “the system makes an arbitrary decisions that you as an application developer can’t know about.” Ultimately, the power management API as it existed in XP was never intended to be used beyond its basic functionality. Why else would the specification be so unclear and sparse in detail?