Table 3-17 Power Management notification interface
| Function | Description |
|---|---|
| RequestPowerNotifications | Registers an application process with Power Manager to receive power notifications. Power Manager then sends the following notification messages: |
| ■ PBT_RESUME The system resumes from Suspend state. | |
| ■ PBT_POWERSTATUSCHANGE The system transitions between AC power and battery power. | |
| ■ PBT_TRANSITION The system changes to a new power state. | |
| ■ PBT_POWERINFOCHANGE The battery status changes. This message is only valid if a battery driver is loaded. | |
| StopPowerNotifications | Unregisters an application process so it no longer receives power notifications. |
The following sample code illustrates how to use power notifications:
// Size of a POWER_BROADCAST message.
DWORD cbPowerMsgSize =
sizeof POWER_BROADCAST + (MAX_PATH * sizeof TCHAR);
// Initialize a MSGQUEUEOPTIONS structure.
MSGQUEUEOPTIONS mqo;
mqo.dwSize = sizeof(MSGQUEUEOPTIONS);
mqo.dwFlags = MSGQUEUE_NOPRECOMMIT;
mqo.dwMaxMessages = 4;
mqo.cbMaxMessage = cbPowerMsgSize;
mqo.bReadAccess = TRUE;
//Create a message queue to receive power notifications.
HANDLE hPowerMsgQ = CreateMsgQueue(NULL, &mqo);
if (NULL == hPowerMsgQ) {
RETAILMSG(1, (L"CreateMsgQueue failed: %x\n", GetLastError()));
return ERROR;
}
// Request power notifications.
HANDLE hPowerNotifications = RequestPowerNotifications(hPowerMsgQ,
PBT_TRANSITION | PBT_RESUME | PBT_POWERINFOCHANGE);
// Wait for a power notification or for the app to exit.
while(WaitForSingleObject(hPowerMsgQ, FALSE, INFINITE) == WAIT_OBJECT_0) {
DWORD cbRead;
DWORD dwFlags;
POWER_BROADCAST *ppb = (POWER_BROADCAST*) new BYTE[cbPowerMsgSize];
// Loop through in case there is more than 1 msg.
while(ReadMsgQueue(hPowerMsgQ, ppb, cbPowerMsgSize, &cbRead, 0, &dwFlags)) {
// Perform action according to the message type.
}
}
Device Driver Interface
In order to integrate with the Power Manager, device drivers must support a set of I/O controls (IOCTLs). Power Manager uses these to query device-specific power capabilities as well as to set and change the device's power state, as illustrated in Figure 3-10. Based on the Power Manager IOCTLs, the device driver should put the hardware device into a corresponding power configuration.
Figure 3-10 Power Manager and device driver interaction
Power Manager uses the following IOCTLs to interact with device drivers:
■ IOCTL_POWER_CAPABILITIES Power Manager checks the power management capabilities of the device driver. The returned information should reflect the capabilities of the hardware and the driver managing the hardware device. The driver must return only supported Dx states.
■ IOCTL_POWER_SET Power Manager forces the driver to switch to a specified Dx state. The driver must perform the power transition.
■ IOCTL_POWER_QUERY Power Manger checks to see if the driver is able to change the state of the device.
■ IOCTL_POWER_GET Power Manager wants to determine the current power state of the device.
■ IOCTL_REGISTER_POWER_RELATIONSHIP Power Manager notifies a parent driver to register all child devices that it controls. Power Manager sends this IOCTL only to devices that include the POWER_CAP_PARENT flag in the Flags member of the POWER_CAPABILITIES structure.
To ensure reliable power management, device drivers should not change their own internal power state without the involvement of Power Manager. If a driver requires a power state transition, the driver should use the DevicePowerNotify function to request the power state change. The driver can then change its internal power state when Power Manager sends a power state change request back to the driver.
Application Interface
The application interface provides functions that applications can use to manage the power state of the system and of individual devices through Power Manager. Table 3-18 summarizes these power management functions.
Table 3-18 Application interface
| Function | Description |
|---|---|
| GetSystemPowerState | Retrieves the current system power state. |
| SetSystemPowerState | Requests a power state change. When switching to Suspend mode, the function will return after the resume because suspend is transparent to the system. After the resume, you can analyze the notification message to identify that the system resumed from suspend. |
| SetPowerRequirement | Requests a minimal power state for a device. |
| ReleasePowerRequirement | Releases a power requirement previously set with the SetPowerRequirement function and restores the original device power state. |
| GetDevicePower | Retrieves the current power state of a specified device. |
| SetDevicePower | Requests a power state change for a device. |