QSessionManager Class Reference

The QSessionManager class provides access to the session manager. More...

#include <qsessionmanager.h>

Inherits QObject.

List of all member functions.

Public Members

• QString sessionId () const
• bool allowsInteraction () 
• bool allowsErrorInteraction () 
• void release () 
• void cancel () 
• enum RestartHint { RestartIfRunning, RestartAnyway, RestartImmediately, RestartNever }
• void setRestartHint ( RestartHint ) 
• RestartHint restartHint () const
• void setRestartCommand ( const QStringList & ) 
• QStringList restartCommand () const
• void setDiscardCommand ( const QStringList & ) 
• QStringList discardCommand () const
• void setProperty ( const QString & name, const QString & value ) 
• void setProperty ( const QString & name, const QStringList & value ) 
• bool isPhase2 () const
• void requestPhase2 () 

Detailed Description

The QSessionManager class provides access to the session manager during a session management action. In Qt, session management actions are handled in the two virtual functions QApplication::commitData() and QApplication::saveState(). Both functions provide a reference to a session manager object as argument, thus allowing the application to communicate with the session manager.

During a session management action, i.e. within one of the two mentioned functions, no user interaction is possible, unless the application got explicit permission from the session manager. An ordinary permission can be requested with allowsInteraction(). With allowsErrorInteraction(), applications can ask for a higher priority interaction permission in case an error occured.

Another important function is cancel(), which asks the session manager to cancel the shutdown process.

For sophisticated session managers as provided on Unix, QSessionManager offers further possibilites to finetune an application's session management behaviour: setRestartCommand(), setDiscardCommand(), setRestartHint(), setProperty(), requestPhase2(). Please see the respective function descriptions for further details.

Member Function Documentation

bool QSessionManager::allowsErrorInteraction ()

Like allowsInteraction() but tells the session manager in addition that an error occured. Session managers may treat error interaction requests with higher priority. That means it is more likely that an error interaction is granted. However, you are still not guaranteed that the session manager will follow your request.

See also: allowsInteraction(), release() and cancel().

bool QSessionManager::allowsInteraction ()

Asks the session manager for permission to interact with the user. Returns TRUE if the interaction was granted, FALSE otherwise.

The rationale behind this is to make it possible to synchronize user interaction during a shutdown. Fancy session managers on multitasking operating systems may ask all applications simultaniously to commit their data, which results in a much faster shutdown.

After the interaction is is recommended (though not necessary) to release the session manager with a call to release(). This way, other applications may get the chance to interact with the user while your application is still busy saving data.

If the user decides to cancel the shutdown process during the interaction phase, inform the session manager with a call to cancel().

Here's an example usage of the mentioned functions that may occur in the QApplication::commitData() function of an application:

void MyApplication::commitData( QSessionManager& sm ) {
    if ( sm.allowsInteraction() ) {
        switch ( QMessageBox::warning( yourMainWindow, "Application Name",
                                        "Save changes to Document Foo?",
                                        tr("&Yes"),
                                        tr("&No"),
                                        tr("Cancel"),
                                        0, 2) ) {
        case 0: // yes
            sm.release();
            // save document here. If saving fails, call sm.cancel()
            break;
        case 1: // no
            break;
        default: // cancel
            sm.cancel();
            break;
        }
    } else {
        // we did not get permission to interact, do something reasonable instead.
    }
}

If an error occured within the application while saving its data, you may want to use allowsErrorInteraction() instead.

See also: QApplication::commitData(), release() and cancel().

void QSessionManager::cancel ()

Tells the session manager to cancel the shutdown process. Applications should not call this function without asking the user first.

See also: allowsInteraction() and allowsErrorInteraction().

QStringList QSessionManager::discardCommand () const

Returns the currently set discard command.

See also: setDiscardCommand(), restartCommand() and setRestartCommand().

bool QSessionManager::isPhase2 () const

Returns whether the session manager is currently performing a second session management phase.

See also: requestPhase2().

void QSessionManager::release ()

Releases the session manager after an interaction phase.

See also: allowsInteraction() and allowsErrorInteraction().

void QSessionManager::requestPhase2 ()

Requests a second session management phase for the application. The application may then simply return from the QApplication::commitData() or QApplication::saveState() function. The respective function will be called again after the first session management phase has been finished, this time with isPhase2() returning TRUE.

The two phases are useful for applications like X11 window manager, that need to store informations about other application's windows and therefore have to wait until these applications finished their respective session management tasks.

See also: isPhase2().

QStringList QSessionManager::restartCommand () const

Returns the currently set restart command.

See also: setRestartCommand() and restartHint().

QString QSessionManager::sessionId () const

Returns the identifier of the current session.

If the application has been restored from an earlier session, this identifier is the same as it was in that previous session.

See also: QApplication::sessionId().

void QSessionManager::setDiscardCommand ( const QStringList & )

See also: discardCommand() and setRestartCommand().

void QSessionManager::setProperty ( const QString & name, const QString & value )

Low-level write access to the application's identification and state record kept in the session manager.

void QSessionManager::setProperty ( const QString & name, const QStringList & value )

Low-level write access to the application's identification and state record kept in the session manager.

void QSessionManager::setRestartCommand ( const QStringList & command )

If the session manager is capable of restoring sessions, it will execute command in order to restore the application. The command defaults to

               appname -session  id

The -session option is mandatory, otherwise QApplication can not tell whether it has been restored or what the current session identifier is. See QApplication::isSessionRestored() and QApplication::sessionId() for details. If your application is very simply, it may be possible to store the entire application state in additional command line options. In general, this is a very bad idea, since command lines are often limited to a few hundred bytes. Instead, use temporary files or a database for this purpose. By marking the data with the unique sessionId(), you will be able to restore the application in a future session.

See also: restartCommand(), setDiscardCommand() and setRestartHint().

void QSessionManager::setRestartHint ( RestartHint hint )

Sets the application's restart hint to hint. The restart hint defines, under what circumstances an application should be restarted by the session manager in the next session.

The following values are possible:

• RestartIfRunning - This is the default hint. If the application still runs by the time the session is shut down, it shall be restarted.
• RestartAnyway - Restart the application in the next session, regardless whether it runs at the end of this session or not. This is in particulary useful for configuration utilities that just run during startup and quit themselves after finishing their task.
• RestartImmediately - Ensure that the application runs all the time. If it exits during the session for whatever reason, restart it immediately. This might be useful for desktop utilities that are supposed to run permanentely, for example a file manager.
• RestartNever - Do not restart this application under any circumstances.

The default hint is RestartIfRunning. Note that these flags are only hints, a session manager may or may not obey them.

Preferrably, the restart hint shall be defined in QApplication::saveState() since most session managers perform a checkpoint immediately after an application's startup.

See also: restartHint().

Search the documentation, FAQ, qt-interest archive and more (uses www.troll.no):

This file is part of the Qt toolkit, copyright © 1995-99 Troll Tech, all rights reserved.