SystemSuspend Class Reference
[QtBaseModule]

Detailed Description

The SystemSuspend class manages entering and leaving system suspend.

The SystemSuspend provides a Qt Extended Server Task. Qt Extended Server Tasks are documented in full in the QtopiaServerApplication class documentation.

Server components may directly use the SystemSuspend interface to enter and monitor the suspend state. Non-server based applications should use the SuspendService to do the same.

The system suspend state is expected to be a very low, but non-destructive, power saving state. As some hardware devices may need to be shutdown before or reinitialized after entry into the suspend state, integrators can provide objects that implement the SystemSuspendHandler interface that will be called before the system enters suspend and after the system leaves it.

As SystemSuspend is a server task, and not a class, components within the server must access it as such. For example, for a server component to put the device into suspend,

    SystemSuspend *suspend = qtopiaTask<SystemSuspend>();
    qWarning() << "About to suspend!";
    if(suspend->suspendSystem())
      qWarning() << "Resumed from suspend!";
    else
      qWarning() << "Suspend failed";

As applications cannot access server tasks directly, they may use the Suspend service.

    QtopiaServiceRequest req("Suspend", "suspend()");
    req.send();

This class is part of the Qt Extended server and cannot be used by other Qt Extended applications.

See also SystemSuspendHandler and SuspendService.

Member Function Documentation

bool SystemSuspend::suspendSystem ()   [pure virtual slot]

Request that the system be suspended. The system will block in this method until execution is resumed. The method returns true if the suspension was successful, and false otherwise.

When called, all tasks in the system that implement the SystemSuspendHandler are instantiated. If any of these tasks returns false from the SystemSuspendHandler::canSuspend() method, the suspend is canceled and the systemSuspendCanceled() signal is emitted. Otherwise, the SystemSuspendHandler::suspend() methods are called on the tasks in reverse order. That is, the task with the highest interface priority is called last. It is assumed that this last task will actually perform the hardware suspend - possibly using the standard "apm --suspend" system call.

Once all the tasks have successfully completed the suspend, the SystemSuspendHandler::wake() method is invoked on each in-order. This is done immediately after the last invokation of the SystemSuspendHandler::suspend() method, so it is important that this last handler actually suspends the device or, from the users perspective, the device will suspend and immediately resume.

void SystemSuspend::systemActive ()   [signal]

Emitted whenever the system has completed resuming from suspend.

void SystemSuspend::systemSuspendCanceled ()   [signal]

Emitted whenever a system suspend has been requested but a SystemSuspendHandler reported that it was not in a state to suspend. The suspendSystem() call that requested the suspend will return false.

void SystemSuspend::systemSuspending ()   [signal]

Emitted whenever the system begins suspending. This is emitted after the SystemSuspendHandlers have all reported that the system is in a state to suspend.

Following the systemSuspending() signal, a systemWaking() and systemActive() signals are guarenteed.

void SystemSuspend::systemWaking ()   [signal]

Emitted whenever the system is in the process of resuming from suspend.