Define System Power State Classes (Compact 2013)

3/26/2014

The Power Manager sample platform dependent driver (PDD) is made up of five source files. You modify four of these source files to implement new system power states.

Platform Manager Sample PDD Source Files

Source File	Description
Pwstates.h	Header file containing system power state names and classes. This file defines the PowerState base class, along with a derived class for each system power state.
Pwstates.cpp	Source file containing methods for the PowerState class and the derived system power state classes. These methods manage timers and implement the functionality for state transitions.
Platform.cpp	Platform-specific code for Power Manager. This source file contains the functionality that Platform Manager uses to manage devices on your platform.
Pwstatemgr.h	Header file containing the PowerStateManager class and support classes.
Pwstatemgr.cpp	Source file containing methods for the PowerStateManager class and support classes. These methods instantiate system power state classes and implement the Power Manager event loop.

Although most system power state functionality resides in Pwstates.h and Pwstates.cpp, some functionality in Platform.cpp affects the behavior of system power state transitions. For more information about how to modify this file, see Make Platform-Specific Modifications to Power Manager.

To declare a new system power state in the Platform Manager source code, you edit Pwstates.h and add new definitions for your system power state class.

To define a new system power state class

1. In Pwstates.h, define a new string constant for your system power state. Note that this string constant must consist of lowercase letters only.

2. Add an enumeration to PLATFORM_ACTIVITY_STATE for your new system power state.

3. Define a derived system power state C++ class by subclassing the PowerState base class.

For example, you could add an Off state to the Power Manager sample PDD. Off is the state when the system is completely powered off. The following code examples show how to add this Off state to Pwstates.h.

First, define a string constant for your new Off system power state:

#define STRING_OFF _T("off")

Next, add an Off enumeration to PLATFORM_ACTIVITY_STATE:

typedef enum { On,  UserIdle,  Unattended,  Resuming,  Suspend,  ScreenOff,  BacklightOff,  ColdReboot,  Reboot,  Off, // The system is powered off UnknownState = (-1) } PLATFORM_ACTIVITY_STATE, *PPLATFORM_ACTIVITY_STATE;

Create a new C++ class definition for your Off system power state. This class must derive from the PowerState class.

class PowerStateOff : public PowerState {  public:   PowerStateOff (PowerStateManager * pPwrStateMgr, PowerState * pNextPowerState = NULL)         : PowerState (pPwrStateMgr, pNextPowerState)     {};    virtual void EnterState ();    virtual PLATFORM_ACTIVITY_EVENT WaitForEvent (DWORD dwTimeouts = INFINITE,                                                   DWORD dwNumOfExternEvent = 0,                                                   HANDLE * pExternEventArray = NULL);     virtual PLATFORM_ACTIVITY_STATE GetState ()    {        return Off;     };    virtual LPCTSTR GetStateString ()    {        return STRING_OFF;     };    virtual DWORD StateValidateRegistry (DWORD, DWORD)     {        return PowerState::StateValidateRegistry (4, POWER_STATE_OFF);     }};

As shown in the preceding example, your system power state class constructor must use an initializer list for the PowerState base class, passing a pointer to the PowerStateManager object and the next PowerState object that is passed to your constructor.

PowerState declares a set of virtual methods that you can override to define the functionality of your system power state. Two of these methods are abstract, which means that you must implement them in your derived system power state class:

PowerState Required Methods

Required Method	Description
GetState	Returns the PLATFORM_ACTIVITY_STATE enumeration for this system power state.
GetStateString	Returns the lowercase string constant definition for this system power state.

For the remaining methods, you can override them with your own definitions or you can use the default methods of PowerState if these meet your requirements. You will likely want to override the methods EnterState and WaitForEvent (as explained in Implement System Power State Methods) because these methods determine how your system power state handles state transitions.

GetState, GetStateString, and StateValidateRegistry are relatively simple methods that are typically defined inline in your class definition, as shown in the example. GetState returns the enumeration type for your system power state, and GetStateString returns the string constant for your system power state. In the above example, the GetState method returns the PLATFORM_ACTIVITY_STATE enumeration Off, and the GetStateString method returns the string constant STRING_OFF.

The StateValidateRegistry method calls the base class StateValidateRegistry method to verify that the registry contains a registry key for this system power state. If StateValidateRegistry is unable to find a registry key for this system power state, it creates a new registry key for the system power state, setting the device power state registry value to the argument passed in this first parameter and setting and the power hint flag registry value to the argument passed in the second parameter. In this example, the call to StateValidateRegistry specifies that the default device power state for all devices on the platform is D4 (Powered Off). The second parameter is set to POWER_STATE_OFF to specify that applications can call the Power Manager SetSystemPowerState function and pass in the POWER_STATE_OFF hint to request that Power Manager transition the system to the Off state. If SetSystemPowerState is unable to find or create a registry key for your system power state, it returns an error; otherwise, it returns ERROR_SUCCESS.

See Also

Concepts

Define New System Power States