Using the PowerState API

It's been a full week since my last post but I've been a bit busy writing sql scripts for an upcoming project at work.. But I did take a couple of minutes to write a simple Windows Mobile Powerstate API sample. Only two function calls are covered but together they hold the last bits you need to be able to write an application that "wakes" up the device at a set time and after performing various tasks are capable to return the device back to the previous state.

I'll show you how right now!

By now you already know how to use the notification library that comes with Windows Mobile. The problem with this API is that although capable of executing an application at a specific time it will not wake the device. In other words; you can initiate a thread but you won't be able to access peripheral devices such as the GPS receiver, open up an internet connection or send text messages. These are all things you often want to do when beeing able to execute applications on set times.
By applying a bit of PowerState magic this small issue may easily be solved.

First of you want to know the current power state of the device. This can easily be found out be calling GetSystemPowerState.

        [DllImport("coredll.dll", SetLastError = false)]
        public static extern uint GetSystemPowerState(string sPowerStateName, uint iNameLen, ref uint Flags);

This function will return both the name of the current state as well as all the power state flags that has been set. Power state flags are a simple 32 bit bitmask. The header file declares the different power state flags as constants but I've choosen to declare them as a enum.

    public enum POWER_STATE
    {
        ON              = 0x10000       // on state
        , OFF           = 0x20000       // no power, full off
        , CRITICAL      = 0x40000       // critical off
        , BOOT          = 0x80000       // boot state
        , IDLE          = 0x100000      // idle state
        , SUSPEND       = 0x200000      // suspend state
        , UNATTENDED    = 0x400000      // unattended state
        , RESET         = 0x800000      // reset state
        , USERIDLE      = 0x1000000     // user idle state
        , BACKLIGHTON   = 0x2000000     // device screen backlight on
        , PASSWORD      = 0x1000000     // this state is password protected
    }

Calling GetSystemPowerState before applying a new power state allows you to save the current state and then re-apply it after you've done whatever it is you wanna do. SetSystemPowerState is just as easy to use as its equivelent Get-function.

        [DllImport("coredll.dll", SetLastError = false)]
        public static extern uint SetSystemPowerState(string sPowerStatename, POWER_STATE nFlags, uint nForce);

You can pretty much ignore the PowerStateName parameter. nFlags speaks for itself and nForce can be used to force the device into a specific power state.

When using SetSystemPowerState to wake the device you basically call it passing POWER_STATE.ON as the nFlags parameter. And that's it..

I've written a small sample showing you how to use both function calls as well as how the POWER_STATE bitmask works. Enjoy!

            uint iRet;
            uint nFlags = 0;
            // This would be an excellent time to get aquinted with the StringBuilder object but 
            // let's do it the cheap way for now.
            string sPowerStateName = "                      ";
            iRet = WinCE.Powerstate.GetSystemPowerState(sPowerStateName, (uint)sPowerStateName.Length, ref nFlags);
            if (iRet != 0)
            {
                MessageBox.Show("Failed to retrieve system power state");
                return;
            }
            MessageBox.Show("Powerstate is: " + sPowerStateName);

            bool IsOn = Convert.ToBoolean(nFlags & (uint)POWER_STATE.ON);
            bool IsOff = Convert.ToBoolean(nFlags & (uint)POWER_STATE.OFF);
            bool IsCritical = Convert.ToBoolean(nFlags & (uint)POWER_STATE.CRITICAL);
            bool IsBoot = Convert.ToBoolean(nFlags & (uint)POWER_STATE.BOOT);
            bool IsIdle = Convert.ToBoolean(nFlags & (uint)POWER_STATE.IDLE);
            bool IsSuspended = Convert.ToBoolean(nFlags & (uint)POWER_STATE.SUSPEND);
            bool IsUnattended= Convert.ToBoolean(nFlags & (uint)POWER_STATE.UNATTENDED);
            bool IsReset = Convert.ToBoolean(nFlags & (uint)POWER_STATE.RESET);
            bool IsUserIdle = Convert.ToBoolean(nFlags & (uint)POWER_STATE.USERIDLE);
            bool IsBackLightOn = Convert.ToBoolean(nFlags & (uint)POWER_STATE.BACKLIGHTON);
            bool IsPassword = Convert.ToBoolean(nFlags & (uint)POWER_STATE.PASSWORD);

            uint iRet;
            iRet = WinCE.Powerstate.SetSystemPowerState(null, POWER_STATE.OFF, 1);
            if (iRet == 0)
                MessageBox.Show("Successfully set new power state");
            else
                MessageBox.Show("Failed to set new power state");