PowerMgr functions

Functions
EXTERN_C CCAUXDLL_API POWERMGRHANDLE CCAUXDLL_CALLING_CONV	GetPowerMgr (void)
EXTERN_C CCAUXDLL_API void CCAUXDLL_CALLING_CONV	PowerMgr_release (POWERMGRHANDLE)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	PowerMgr_registerControlledSuspendOrShutDown (POWERMGRHANDLE, PowerMgrConf conf)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	PowerMgr_getConfiguration (POWERMGRHANDLE, PowerMgrConf *conf)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	PowerMgr_getPowerMgrStatus (POWERMGRHANDLE, PowerMgrStatus *status)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	PowerMgr_setAppReadyForSuspendOrShutdown (POWERMGRHANDLE)
EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV	PowerMgr_hasResumed (POWERMGRHANDLE, bool *resumed)

Detailed Description

Functions in the PowerMgr class

Function Documentation

GetPowerMgr()

EXTERN_C CCAUXDLL_API POWERMGRHANDLE CCAUXDLL_CALLING_CONV CrossControl::GetPowerMgr

(

void

)

Factory function that creates instances of the PowerMgr object.

Supported Platform(s): XL, XL5, XM, XM9, XS, XA, VC, VA, VS, VI2, V700, Yukon, V510, V710, V1000, V1200, X1200

Returns

POWERMGRHANDLE to an allocated PowerMgr structure. The returned handle needs to be deallocated using the PowerMgr::Release() method when it's no longer needed. Returns NULL if it fails to allocate memory.

Example Usage:

    CrossControl::eErr err;
    POWERMGRHANDLE pPowerMgr = ::GetPowerMgr();
    BATTERYHANDLE pBattery   = ::GetBattery();
 
    assert(pPowerMgr);
    assert(pBattery);
 
    // Register a separate exit handler for the case where OS is initiating the shutdown. The Application must handle
    // this case itself.
    atexit(fnExit);
 
    bool bBatt = false;
    Battery_isBatteryPresent(pBattery, &bBatt);
    if (bBatt) // Ask user wich configuration to use...
        cout << "Choose configuration to use, 0 - Normal, 1 - Application Controlled , 2 - Battery Suspend" << endl;
    else
        cout << "Choose configuration to use, 0 - Normal, 1 - Application Controlled" << endl;
 
    cin >> suspendConfiguration;
    Battery_release(pBattery);
 
    // Register that this application needs to delay suspend/shutdown
    // This should be done as soon as possible.
    // Then the app must poll getPowerMgrStatus() and allow the suspend/shutdown with setAppReadyForSuspendOrShutdown().
    // Depending on application design, this might be best handled in a separate thread.
    err = PowerMgr_registerControlledSuspendOrShutDown(pPowerMgr, (PowerMgrConf)suspendConfiguration);
 
    cout << "suspendConfiguration " << suspendConfiguration << endl;
 
    if (err == ERR_SUCCESS)
        cout << "Registered to powerMgr." << endl;
    else
        cout << "Error(" << err << ") in function registerControlledSuspendOrShutDown: " << GetErrorStringA(err)
             << endl;
 
    test_powermgr(pPowerMgr);
 
    PowerMgr_release(pPowerMgr);

PowerMgr_getConfiguration()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::PowerMgr_getConfiguration	(	POWERMGRHANDLE	,
		PowerMgrConf *	conf
	)

Get the configuration that is in use.

Supported Platform(s): XL, XL5 ,XM, XM9, XS, XA, VC, VA, VS, VI2, V700, Yukon, V510, V710, V1000, V1200, X1200

Parameters

conf	The configuration in use.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

Example Usage:

                CrossControl::PowerMgrConf conf;
                err = PowerMgr_getConfiguration(pPowerMgr, &conf);
                if (err == ERR_SUCCESS)
                {
                    switch (conf)
                    {
                    case Normal:
                        cout << "PowerMgrConf is now: Normal" << endl;
                        break;
                    case ApplicationControlled:
                        cout << "PowerMgrConf is now: ApplicationControlled" << endl;
                        break;
                    case BatterySuspend:
                        cout << "PowerMgrConf is now: BatterySuspend" << endl;
                        break;
                    }
                }
                else
                {
                    cout << "Error(" << err << ") in function getConfiguration: " << GetErrorStringA(err) << endl;
                }

PowerMgr_getPowerMgrStatus()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::PowerMgr_getPowerMgrStatus	(	POWERMGRHANDLE	,
		PowerMgrStatus *	status
	)

Get the current status of the PowerMgr. This functions should be called periodically, to detect when suspend or shutdown requests arrive.

Supported Platform(s): XL, XL5 ,XM, XM9, XS, XA, VC, VA, VS, VI2, V700, Yukon, V510, V710, V1000, V1200, X1200

Parameters

status

The current status.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

Example Usage:

    while (1)
    {
        OSSleep(500);
 
        PowerMgrStatus status;
        err = PowerMgr_getPowerMgrStatus(pPowerMgr, &status);
        if (err == ERR_SUCCESS)
        {
            switch (status)
            {
            case NoRequestsPending: // Wait until a PowerMgr request arrives...
                break;
 
            case ShutdownPending: {
                // Shutdown by means of power button or on/off signal are caught here.
                os_shutdown = false;
 
                cout << "A shutdown request detected. App should now do what it needs to do before shutdown can be "
                        "performed."
                     << endl;
                cout << "Press Enter when ready to shutdown... " << endl;
 
                // Make sure to clear cin buffer before read
                std::cin.clear();
                std::cin.ignore(100, '\n');
                cin.get();
                cout << "Signalling that app is ready..." << endl;
                err = PowerMgr_setAppReadyForSuspendOrShutdown(pPowerMgr);
                if (err != ERR_SUCCESS)
                {
                    cout << "Error(" << err << ") in function setAppReadyForSuspendOrShutdown: " << GetErrorStringA(err)
                         << endl;
                }
                return; // exit test appp
            }
            case SuspendPending: {
                os_shutdown = false;
 
                cout << "A suspend request detected. App should now do what it needs to do before suspend can be "
                        "performed."
                     << endl;
                cout << "Press Enter when ready to suspend... " << endl;
 
                // Make sure to clear cin buffer before read
                std::cin.clear();
                std::cin.ignore(100, '\n');
                cin.get();
                cout << "Signalling that app is ready..." << endl;
                err = PowerMgr_setAppReadyForSuspendOrShutdown(pPowerMgr);
                if (err != ERR_SUCCESS)
                {
                    cout << "Error(" << err << ") in function setAppReadyForSuspendOrShutdown: " << GetErrorStringA(err)
                         << endl;
                }
            }
            break;
 
            default:
                cout << "Error: Invalid status returned from getPowerMgrStatus!" << endl;
                break;
            }
 
            // Wait for resume after notifying that we are ready to suspend
            if (status == SuspendPending)
            {
                bool b = false;
                while (!b)
                {
                    OSSleep(100);
                    cout << "." << endl;
 
                    err = PowerMgr_hasResumed(pPowerMgr, &b);
                    if (err != ERR_SUCCESS)
                    {
                        cout << "Error(" << err << ") in function hasResumed: " << GetErrorStringA(err) << endl;
                    }
                }
                cout << "System is now resumed from suspend mode!" << endl
                     << "Now we will soon re-register using the registerControlledSuspendOrShutDown function!" << endl;
 
                // Expecting to get configuration Normal after resume from suspend
 
                CrossControl::PowerMgrConf conf;
                err = PowerMgr_getConfiguration(pPowerMgr, &conf);
                if (err == ERR_SUCCESS)
                {
                    switch (conf)
                    {
                    case Normal:
                        cout << "PowerMgrConf is now: Normal" << endl;
                        break;
                    case ApplicationControlled:
                        cout << "PowerMgrConf is now: ApplicationControlled" << endl;
                        break;
                    case BatterySuspend:
                        cout << "PowerMgrConf is now: BatterySuspend" << endl;
                        break;
                    }
                }
                else
                {
                    cout << "Error(" << err << ") in function getConfiguration: " << GetErrorStringA(err) << endl;
                }
 
                // Re-register, do this as soon as possible after resume/startup
                PowerMgr_registerControlledSuspendOrShutDown(pPowerMgr, setConfiguration);
                if (err == ERR_SUCCESS)
                    cout << "Re-registered to powerMgr.  Ctrl-C to exit." << endl;
                else
                    cout << "Error(" << err
                         << ") in function registerControlledSuspendOrShutDown: " << GetErrorStringA(err) << endl;
            }
        }
        else
        {
            cout << "Error(" << err << ") in function getPowerMgrStatus: " << GetErrorStringA(err) << endl;
        }
    }

PowerMgr_hasResumed()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::PowerMgr_hasResumed	(	POWERMGRHANDLE	,
		bool *	resumed
	)

This function can be used in a suspend-resume scenario. After the application has used setAppReadyForSuspendOrShutdown() to init the suspend, this function may be polled in order to detect when the system is up and running again. Calling this function before calling setAppReadyForSuspendOrShutdown will return resumed = true.

Supported Platform(s): XL, XL5, XM, XM9 (CC Linux), VC, VA, VS, VI2, V700, Yukon, V510, V710, V1000, V1200, X1200

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

Example Usage:

    while (1)
    {
        OSSleep(500);
 
        PowerMgrStatus status;
        err = PowerMgr_getPowerMgrStatus(pPowerMgr, &status);
        if (err == ERR_SUCCESS)
        {
            switch (status)
            {
            case NoRequestsPending: // Wait until a PowerMgr request arrives...
                break;
 
            case ShutdownPending: {
                // Shutdown by means of power button or on/off signal are caught here.
                os_shutdown = false;
 
                cout << "A shutdown request detected. App should now do what it needs to do before shutdown can be "
                        "performed."
                     << endl;
                cout << "Press Enter when ready to shutdown... " << endl;
 
                // Make sure to clear cin buffer before read
                std::cin.clear();
                std::cin.ignore(100, '\n');
                cin.get();
                cout << "Signalling that app is ready..." << endl;
                err = PowerMgr_setAppReadyForSuspendOrShutdown(pPowerMgr);
                if (err != ERR_SUCCESS)
                {
                    cout << "Error(" << err << ") in function setAppReadyForSuspendOrShutdown: " << GetErrorStringA(err)
                         << endl;
                }
                return; // exit test appp
            }
            case SuspendPending: {
                os_shutdown = false;
 
                cout << "A suspend request detected. App should now do what it needs to do before suspend can be "
                        "performed."
                     << endl;
                cout << "Press Enter when ready to suspend... " << endl;
 
                // Make sure to clear cin buffer before read
                std::cin.clear();
                std::cin.ignore(100, '\n');
                cin.get();
                cout << "Signalling that app is ready..." << endl;
                err = PowerMgr_setAppReadyForSuspendOrShutdown(pPowerMgr);
                if (err != ERR_SUCCESS)
                {
                    cout << "Error(" << err << ") in function setAppReadyForSuspendOrShutdown: " << GetErrorStringA(err)
                         << endl;
                }
            }
            break;
 
            default:
                cout << "Error: Invalid status returned from getPowerMgrStatus!" << endl;
                break;
            }
 
            // Wait for resume after notifying that we are ready to suspend
            if (status == SuspendPending)
            {
                bool b = false;
                while (!b)
                {
                    OSSleep(100);
                    cout << "." << endl;
 
                    err = PowerMgr_hasResumed(pPowerMgr, &b);
                    if (err != ERR_SUCCESS)
                    {
                        cout << "Error(" << err << ") in function hasResumed: " << GetErrorStringA(err) << endl;
                    }
                }
                cout << "System is now resumed from suspend mode!" << endl
                     << "Now we will soon re-register using the registerControlledSuspendOrShutDown function!" << endl;
 
                // Expecting to get configuration Normal after resume from suspend
 
                CrossControl::PowerMgrConf conf;
                err = PowerMgr_getConfiguration(pPowerMgr, &conf);
                if (err == ERR_SUCCESS)
                {
                    switch (conf)
                    {
                    case Normal:
                        cout << "PowerMgrConf is now: Normal" << endl;
                        break;
                    case ApplicationControlled:
                        cout << "PowerMgrConf is now: ApplicationControlled" << endl;
                        break;
                    case BatterySuspend:
                        cout << "PowerMgrConf is now: BatterySuspend" << endl;
                        break;
                    }
                }
                else
                {
                    cout << "Error(" << err << ") in function getConfiguration: " << GetErrorStringA(err) << endl;
                }
 
                // Re-register, do this as soon as possible after resume/startup
                PowerMgr_registerControlledSuspendOrShutDown(pPowerMgr, setConfiguration);
                if (err == ERR_SUCCESS)
                    cout << "Re-registered to powerMgr.  Ctrl-C to exit." << endl;
                else
                    cout << "Error(" << err
                         << ") in function registerControlledSuspendOrShutDown: " << GetErrorStringA(err) << endl;
            }
        }
        else
        {
            cout << "Error(" << err << ") in function getPowerMgrStatus: " << GetErrorStringA(err) << endl;
        }
    }

PowerMgr_registerControlledSuspendOrShutDown()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::PowerMgr_registerControlledSuspendOrShutDown	(	POWERMGRHANDLE	,
		PowerMgrConf	conf
	)

Configure the PowerMgr. Call this function once initially to turn on the functionality.

Supported Platform(s): XL, XL5 ,XM, XM9, XS, XA, VC, VA, VS, VI2, V700, Yukon, V510, V710, V1000, V1200, X1200

Parameters

conf	The configuration to use.

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

Example Usage:

    CrossControl::eErr err;
    POWERMGRHANDLE pPowerMgr = ::GetPowerMgr();
    BATTERYHANDLE pBattery   = ::GetBattery();
 
    assert(pPowerMgr);
    assert(pBattery);
 
    // Register a separate exit handler for the case where OS is initiating the shutdown. The Application must handle
    // this case itself.
    atexit(fnExit);
 
    bool bBatt = false;
    Battery_isBatteryPresent(pBattery, &bBatt);
    if (bBatt) // Ask user wich configuration to use...
        cout << "Choose configuration to use, 0 - Normal, 1 - Application Controlled , 2 - Battery Suspend" << endl;
    else
        cout << "Choose configuration to use, 0 - Normal, 1 - Application Controlled" << endl;
 
    cin >> suspendConfiguration;
    Battery_release(pBattery);
 
    // Register that this application needs to delay suspend/shutdown
    // This should be done as soon as possible.
    // Then the app must poll getPowerMgrStatus() and allow the suspend/shutdown with setAppReadyForSuspendOrShutdown().
    // Depending on application design, this might be best handled in a separate thread.
    err = PowerMgr_registerControlledSuspendOrShutDown(pPowerMgr, (PowerMgrConf)suspendConfiguration);
 
    cout << "suspendConfiguration " << suspendConfiguration << endl;
 
    if (err == ERR_SUCCESS)
        cout << "Registered to powerMgr." << endl;
    else
        cout << "Error(" << err << ") in function registerControlledSuspendOrShutDown: " << GetErrorStringA(err)
             << endl;
 
    test_powermgr(pPowerMgr);
 
    PowerMgr_release(pPowerMgr);

PowerMgr_release()

EXTERN_C CCAUXDLL_API void CCAUXDLL_CALLING_CONV CrossControl::PowerMgr_release

(

POWERMGRHANDLE

)

Delete the PowerMgr object.

Supported Platform(s): XL, XL5, XM, XM9, XS, XA, VC, VA, VS, VI2, V700, Yukon, V510, V710, V1000, V1200, X1200

Returns

-

Example Usage:

    CrossControl::eErr err;
    POWERMGRHANDLE pPowerMgr = ::GetPowerMgr();
    BATTERYHANDLE pBattery   = ::GetBattery();
 
    assert(pPowerMgr);
    assert(pBattery);
 
    // Register a separate exit handler for the case where OS is initiating the shutdown. The Application must handle
    // this case itself.
    atexit(fnExit);
 
    bool bBatt = false;
    Battery_isBatteryPresent(pBattery, &bBatt);
    if (bBatt) // Ask user wich configuration to use...
        cout << "Choose configuration to use, 0 - Normal, 1 - Application Controlled , 2 - Battery Suspend" << endl;
    else
        cout << "Choose configuration to use, 0 - Normal, 1 - Application Controlled" << endl;
 
    cin >> suspendConfiguration;
    Battery_release(pBattery);
 
    // Register that this application needs to delay suspend/shutdown
    // This should be done as soon as possible.
    // Then the app must poll getPowerMgrStatus() and allow the suspend/shutdown with setAppReadyForSuspendOrShutdown().
    // Depending on application design, this might be best handled in a separate thread.
    err = PowerMgr_registerControlledSuspendOrShutDown(pPowerMgr, (PowerMgrConf)suspendConfiguration);
 
    cout << "suspendConfiguration " << suspendConfiguration << endl;
 
    if (err == ERR_SUCCESS)
        cout << "Registered to powerMgr." << endl;
    else
        cout << "Error(" << err << ") in function registerControlledSuspendOrShutDown: " << GetErrorStringA(err)
             << endl;
 
    test_powermgr(pPowerMgr);
 
    PowerMgr_release(pPowerMgr);

PowerMgr_setAppReadyForSuspendOrShutdown()

EXTERN_C CCAUXDLL_API eErr CCAUXDLL_CALLING_CONV CrossControl::PowerMgr_setAppReadyForSuspendOrShutdown

(

POWERMGRHANDLE

)

Acknowledge that the application is ready for suspend/shutdown. Should be called after a request has been received in order to execute the request. The application must acknowledge a request within 20s (30s for Yukon, V510, V710, V1000, V1200) from when it arrives.

Supported Platform(s): XL, XL5 ,XM, XM9, XS, XA, VC, VA, VS, VI2, V700, Yukon, V510, V710, V1000, V1200, X1200

Returns

error status. 0 = ERR_SUCCESS, otherwise error code. See the enum eErr for details.

Example Usage:

    while (1)
    {
        OSSleep(500);
 
        PowerMgrStatus status;
        err = PowerMgr_getPowerMgrStatus(pPowerMgr, &status);
        if (err == ERR_SUCCESS)
        {
            switch (status)
            {
            case NoRequestsPending: // Wait until a PowerMgr request arrives...
                break;
 
            case ShutdownPending: {
                // Shutdown by means of power button or on/off signal are caught here.
                os_shutdown = false;
 
                cout << "A shutdown request detected. App should now do what it needs to do before shutdown can be "
                        "performed."
                     << endl;
                cout << "Press Enter when ready to shutdown... " << endl;
 
                // Make sure to clear cin buffer before read
                std::cin.clear();
                std::cin.ignore(100, '\n');
                cin.get();
                cout << "Signalling that app is ready..." << endl;
                err = PowerMgr_setAppReadyForSuspendOrShutdown(pPowerMgr);
                if (err != ERR_SUCCESS)
                {
                    cout << "Error(" << err << ") in function setAppReadyForSuspendOrShutdown: " << GetErrorStringA(err)
                         << endl;
                }
                return; // exit test appp
            }
            case SuspendPending: {
                os_shutdown = false;
 
                cout << "A suspend request detected. App should now do what it needs to do before suspend can be "
                        "performed."
                     << endl;
                cout << "Press Enter when ready to suspend... " << endl;
 
                // Make sure to clear cin buffer before read
                std::cin.clear();
                std::cin.ignore(100, '\n');
                cin.get();
                cout << "Signalling that app is ready..." << endl;
                err = PowerMgr_setAppReadyForSuspendOrShutdown(pPowerMgr);
                if (err != ERR_SUCCESS)
                {
                    cout << "Error(" << err << ") in function setAppReadyForSuspendOrShutdown: " << GetErrorStringA(err)
                         << endl;
                }
            }
            break;
 
            default:
                cout << "Error: Invalid status returned from getPowerMgrStatus!" << endl;
                break;
            }
 
            // Wait for resume after notifying that we are ready to suspend
            if (status == SuspendPending)
            {
                bool b = false;
                while (!b)
                {
                    OSSleep(100);
                    cout << "." << endl;
 
                    err = PowerMgr_hasResumed(pPowerMgr, &b);
                    if (err != ERR_SUCCESS)
                    {
                        cout << "Error(" << err << ") in function hasResumed: " << GetErrorStringA(err) << endl;
                    }
                }
                cout << "System is now resumed from suspend mode!" << endl
                     << "Now we will soon re-register using the registerControlledSuspendOrShutDown function!" << endl;
 
                // Expecting to get configuration Normal after resume from suspend
 
                CrossControl::PowerMgrConf conf;
                err = PowerMgr_getConfiguration(pPowerMgr, &conf);
                if (err == ERR_SUCCESS)
                {
                    switch (conf)
                    {
                    case Normal:
                        cout << "PowerMgrConf is now: Normal" << endl;
                        break;
                    case ApplicationControlled:
                        cout << "PowerMgrConf is now: ApplicationControlled" << endl;
                        break;
                    case BatterySuspend:
                        cout << "PowerMgrConf is now: BatterySuspend" << endl;
                        break;
                    }
                }
                else
                {
                    cout << "Error(" << err << ") in function getConfiguration: " << GetErrorStringA(err) << endl;
                }
 
                // Re-register, do this as soon as possible after resume/startup
                PowerMgr_registerControlledSuspendOrShutDown(pPowerMgr, setConfiguration);
                if (err == ERR_SUCCESS)
                    cout << "Re-registered to powerMgr.  Ctrl-C to exit." << endl;
                else
                    cout << "Error(" << err
                         << ") in function registerControlledSuspendOrShutDown: " << GetErrorStringA(err) << endl;
            }
        }
        else
        {
            cout << "Error(" << err << ") in function getPowerMgrStatus: " << GetErrorStringA(err) << endl;
        }
    }