Home · All Classes · Grouped Classes · Annotated · Functions

QtopiaServerApplication Class Reference

The QtopiaServerApplication class provides additional QtopiaApplication functionality. More...

    #include <QtopiaServerApplication>

Inherits QtopiaApplication.

Public Types

Public Functions

Public Slots

Signals

Static Public Members

Related Non-Members

Macros

Additional Inherited Members


Detailed Description

The QtopiaServerApplication class provides additional QtopiaApplication functionality.

Qtopia Server Tasks

The QtopiaServerApplication class acts as a QtopiaApplication instance in Qtopia Server. QtopiaServerApplication is primarily responsible for bringing up and shutting down the Qtopia server and acts as the "core" controller in the system. This class is part of the Qtopia server and cannot be used by other Qtopia applications.

The Qtopia server is structured as a collection of largely independent tasks that are responsible for performing a small, well defined portion of work or functionality which often form the "backend" to other system capabilities. For example, Qtopia's network management APIs ultimately communicate with the QtopiaNetworkServer task, other tasks may operate more independently. Tasks can be thought of as the building blocks that form the Qtopia server, when arranged appropriately.

Tasks are QObjects and may work together by exporting C++ interfaces. Other tasks or modules within the server may request tasks that support a particular interface. For example, when the system is shutting down, all the tasks that provide the SystemShutdownHandler interface are invoked to perform all the necessary cleanup.

The order in which the task objects are instantiated is configurable. Both the configurator and the task developer has a degree of control over the instantiation order. The configurator controls the start up order through the $QPEDIR/etc/Tasks.cfg file which has the following simple syntax:

    # Sample comment for TaskGroup1.  Comments may appear anywhere, as long as
    # the first character in the line is a '#'
    [TaskGroup1]
    TaskName1
    +TaskGroup2
    # Likewise, blank lines, as well as leading and trailing white space is
    # ignored

    [TaskGroup2]
    TaskName2
    TaskName3

Task groups are free-form descriptors used to collect related classes. Task group names may only contain alphanumeric characters and must not not contain spaces. A task name is the name given to the task when it is declared in code. It consists of alphanumeric characters and cannot contain spaces. Groups may be nested hierarchically as shown in the example. Nesting one group in another is exactly the same as pasting the body of the nested group into the parent group. The above Tasks.cfg file is equivalent to:

    [TaskGroup1]
    TaskName1
    TaskName2
    TaskName3

    [TaskGroup2]
    TaskName2
    TaskName3

Reserved task Group Names

The following group names are reserved and have a special purpose:

Group NameDescription
prestartupThe prestartup contains tasks that will be started immediately after Qtopia is executed.
startupThe startup group contains tasks to be launched at startup.
excludeThe exclude group contains tasks that, while present in the server, will never be created. Adding a task to the exclude group is equivalent to removing it from the server.
AllThe All group is a catch all tasks whose startup preference is not otherwise specified.

How these groups interact will be covered shortly.

Supported Task Types

Tasks are constructed in one of two ways: preemptively or on-demand.

TypeDescription
Preemptive TasksPreemptive tasks are those started by the system during startup, regardless of whether or not any other task has asked for it.
On-demand TasksOn-demand tasks are those whose creation is deferred until another task requests it be started. Tasks in the startup group in Tasks.cfg are the only tasks that are created preemptively. All other tasks (with the exception of those in the exclude group are started on demand.

While it is possible to instantiate an on-demand task by name, it is generally not advisable as doing so often creates unnecessary coupling within the system. Instead, requesters ask the system to return a task that supports a given interface. Doing so allows a particular implementation to be switched out without any code changes to the requestor.

Marking Tasks to be Started on Demand

Tasks in the Tasks.cfg file can be marked as demand started tasks by appending the :demand to their task name. Similarly, group names can have :demand appended, which is equivalent to adding the designator to each of their containing task or sub-group names. Demand tasks will never be picked by the All catch all task, but are otherwise subject to all ordering primatives.

Tasks Startup Order

The qtopiaTask() and qtopiaTasks() templates are used to request a task interface. qtopiaTask() returns the first task that implements the interface and qtopiaTasks() returns all the tasks that implement the interface. Each of these calls takes an optional boolean parameter to indicate whether the system should instantiate a task to satisfy the request (if needed) or only return tasks that have previously been instantiated.

The order of tasks returned by qtopiaTask() and qtopiaTasks() is controllable through the order in which they appear in the Tasks.cfg file. Consider the Tasks.cfg flattened so that it consists of a list of all groups in the order in which they appear. Each task in this imaginary task list implements zero or more interfaces. The order tasks will be returned when requested by interface is the same order as those tasks appear in this list, with duplicates removed.

As a special "catch-all", primarily to prevent incorrect configuration, the special All task can be added to the startup group. This has the effect of inserting all tasks not otherwise in the startup or exclude groups or explicitly marked as demand started tasks.

While the QtopiaServerApplication class itself is not strictly a task, it is instantiated during startup by the task system in the same way as other tasks under the special task name QtopiaApplication. The QtopiaApplication task should be instantiated immediately after any environment setup or cleanup type tasks as many other tasks have an implicit reliance on its existence.

The order that the system will try and start preemptive tasks and the order in which tasks will be given interface preference can be read from the value space immediately following the QtopiaApplication task executing. The exact schema is:

ItemTypeDescription
/System/Tasks/<TaskName>/Order/StaticintThe preemptive order that the system determined it would launch tasks. This may be different from the actual order if one task demand loads another that would otherwise be loaded later.
/System/Tasks/<TaskName>/Order/LaunchintThe order that the tasks were actually launched in. This key will only exist if the task is active.
/System/Tasks/<TaskName>/Order/InterfaceintThe order that the task will be given when determining interface associations.
/System/Tasks/<TaskName>/StateString"Disable" if the task was in the exclude list, "Active" if the task is running, or "Inactive" if not.

A tutorial on how to develop new server tasks can be found in the Device Integration guide.

Qtopia Server Widgets

There are many cases of Qt widgets being used throughout the Qtopia server that may need to be customized to achieve a desired look and feel. For example, while it supports customization through theming, a customer that wants to replace the Qtopia phone dialer with a "rotary dial" style dialer would need to replace the entire dialer widget.

To simplify the task and minimize the code changes needed to replace visual components of the Qtopia Server, the concept of Qtopia Server Widgets exists. Qtopia Server Widgets splits the definition of a visual component - or server widget - into two parts: the server widget interface (hereafter referred to as the AbstractWidget) and the concrete server widget implementation (ConcreteWidget). While not technically necessary, the AbstractWidget is generally an abstract interface that derives directly from QWidget.

Rather than using the regular new ClassName(parent, flags) syntax for instantiating a widget, the special qtopiaWidget() template method, parameterized on AbstractWidget, is provided. This method uses the server widgets replacement system to look up the ConcreteWidget instance type it should return.

Developers use the QTOPIA_REPLACE_WIDGET(), QTOPIA_REPLACE_WIDGET_WHEN() and QTOPIA_REPLACE_WIDGET_OVERRIDE() macros to provide ConcreteWidget for a particular AbstractWidget. The server widget replacement system then resolves which ConcreteWidget to return by executing the following set of rules in order until a ConcreteWidget is determined.

RuleDescription
Explicitly specifiedThe Trolltech/ServerWidgets configuration file is read to determine if the ConcreteWidget to use has been explicitly specified. The configuration file contains one group, Mapping that contains mappings between AbstractName and ConcreteName. How these two names are determined is discussed below. For example,
    [Mapping]
    BrowserScreen=Wheel
    DialerScreen=Rotary

Unless the specified widget does not exist, the mapping is always honored. That is, using QTOPIA_REPLACE_WIDGET_WHEN() can not override explicitly specified widgets. The special name None will disable the widget, causing qtopiaWidget() to always return null.

Primary DefaultThe primary default is the value of the Mapping/Default key, or Default if not specified. The primary default name is tried as the ConcreteName. Feature dependencies are honored.
Other DefaultsAll ConcreteName's beginning with the primary default name are tried. Feature dependencies are honored.
All ReplacementsAll available ConcreteWidgets are tried. Feature dependencies are honored.

The AbstractName and ConcreteName names used to identify a server widget are derived from the widget class names. AbstractName is set to the AbstractWidget's full name, unless the name begins with QAbstract in which case it is set to the widget class name, minus the QAbstract prefix. The ConcreteName is set to the class name of the ConcreteWidget, unless the class name ends with the AbstractName of the widget it is replacing, in which case it is set to the widget class name minus the AbstractName suffix. These rules are designed to simplify writing mapping files - a class WheelBrowserScreen replacing QAbstractBrowserScreen is written as BrowserScreen=Wheel rather than QAbstractBrowserScreen=WheelBrowserScreen.

The following image also demonstrates the widget selection process:

"Selecting the correct Server Widget"

A tutorial on how to develop new server widgets can be found in the QAbstractServerInterface class documentation and the Device Integration guide.


Member Type Documentation

enum QtopiaServerApplication::ShutdownType

ConstantValueDescription
QtopiaServerApplication::NoShutdown0No shutdown has been requested.
QtopiaServerApplication::RebootSystem2The server terminates and initiates the reboot of the system.
QtopiaServerApplication::RestartDesktop3The server terminates and requests its restart by the calling environment.
QtopiaServerApplication::ShutdownSystem1The server terminates and initiates the shutdown of the system.
QtopiaServerApplication::TerminateDesktop4The server terminates only.


Member Function Documentation

void QtopiaServerApplication::addAggregateObject ( QObject * me, QObject * them )   [static]

Add an object them to me to create an "aggregate" task. Aggregate tasks are designed to work around the limitations in Qt's support for multiple interface inheritance by allowing multiple objects to be "stuck together" to form a single object from the task system's perspective.

For example, consider the following interfaces:

    class ApplicationTypeLauncher : public QObject {};
    QTOPIA_TASK_INTERFACE(ApplicationTypeLauncher);
    class SystemShutdownHandler : public QObject {};
    QTOPIA_TASK_INTERFACE(SystemShutdownHandler);

Using direct inheritance a single task could not implement both interfaces. Instead, a task can create one object that implements the ApplicationTypeLauncher interface and one that implements the SystemShutdownHandler interface and aggregate them together.

    class MyLauncherShutdown : public SystemShutdownHandler
    {
    public:
        MyLauncherShutdown(MyLauncherType *);
    };

    class MyLauncherType : public ApplicationTypeLauncher
    {
    public:
        MyLauncherType()
        {
            MyLauncherShutdown *s = new MyLauncherShutdown(this);
            QtopiaServerApplication::addAggregateObject(this, s);
        }
    };
    QTOPIA_TASK(MyLauncherType, MyLauncherType);
    QTOPIA_TASK_PROVIDES(MyLauncherType, ApplicationTypeLauncher);
    QTOPIA_TASK_PROVIDES(MyLauncherType, SystemShutdownHandler);

When the system attempts to cast a task to a particular interface, it first tries the task object itself, and then each of the aggregate objects for that task.

int & QtopiaServerApplication::argc ()   [static]

Returns the argc reference passed to startup().

char ** QtopiaServerApplication::argv ()   [static]

Returns the argv reference passed to startup().

void QtopiaServerApplication::installQWSEventFilter ( QWSEventFilter * filter )

Install the filter for QWS events. Installing an event filter is equivalent to deriving from QtopiaApplication directly and overriding the QtopiaApplication::qwsEventFilter() method.

Multiple QWS event filters may be installed simultaneously. In this case, each event filter is queried sequentially in the order it was installed. If any filter filters the event, subsequent filters will not be called.

QtopiaServerApplication * QtopiaServerApplication::instance ()   [static]

Return the instantiated QtopiaServerApplication instance. An instance of the class must have been constructed prior to calling this method.

QObject * QtopiaServerApplication::qtopiaTask ( const QByteArray & taskName, bool onlyRunning = false )   [static]

Return the task with name taskName. If onlyRunning is true, the task will be returned only if it has already been instantiated, otherwise it will be instantiated and returned.

void QtopiaServerApplication::removeQWSEventFilter ( QWSEventFilter * filter )

Remove all instances of filter from the list of event filters. This method should be called when an event filter is destroyed. No automatic cleanup is performed.

void QtopiaServerApplication::shutdown ( QtopiaServerApplication::ShutdownType type )   [slot]

Initiates a system shutdown of the specified type.

void QtopiaServerApplication::shutdownRequested ()   [signal]

Emitted whenever the user or an application requests that the system shutdown. A system shutdown is requested by sending a shutdown() message to the QPE/System QCop channel.

Generally a UI will be connected to the shutdownRequested() signal to ask the user what they want to do. This UI should then invoke the shutdown() method to perform the appropriate action.

ShutdownType QtopiaServerApplication::shutdownType ()   [static]

Returns the type of shutdown previously requested by calling shutdown(), or NoShutdown if no shutdown has been requested.

bool QtopiaServerApplication::startup ( int & argc, char ** argv, const QList<QByteArray> & startupGroups )   [static]

Launches server tasks. This method is used to start the Qtopia server and should never be called from other code. Returns true on success, false on failure.

argc and argv should be the values passed to the main() function. startupGroups contains a list of Task groups to start.

QString QtopiaServerApplication::taskConfigFile ()   [static]

Returns the task system's configuration file.

QByteArray QtopiaServerApplication::taskValueSpaceObject ( const QByteArray & taskName )   [static]

Returns the path to an object in the value space that the task taskName can use to store status information. Will return a null byte array if the value space has not been initialized. This method is for task implementors only.

bool QtopiaServerApplication::taskValueSpaceSetAttribute ( const QByteArray & taskName, const QByteArray & attribute, const QVariant & value )   [static]

Sets a value space attribute for task taskName to value. This is a convenience method to simplify the usage of the value space for a task. For more complex usage, tasks should use the taskValueSpaceObject() to request a path, and manually create a QValueSpaceObject for their own use. Returns true upon success; otherwise returns false.

The value remains in the value space until the task is unloaded.


Related Non-Members

T * qtopiaTask ( bool onlyActive = false )

Return a task instance that supports the T interface. If onlyActive is true the system will only select from tasks that are already active. Otherwise, if needed, the system will instantiate tasks to satisfy the request.

QList<T *> qtopiaTasks ( bool onlyActive = false )

Returns all task instances that support the T interface. The instances are in the intended instantiation order. If onlyActive is true the system will only select from tasks that are already active. Otherwise, if needed, the system will instantiate tasks to satisfy the request.

T * qtopiaWidget ( QWidget * parent, Qt::WFlags flags )

Returns a concrete implementation of T, with the specified parent and flags. Concrete implementations are provided with the QTOPIA_REPLACE_WIDGET(), QTOPIA_REPLACE_WIDGET_WHEN() and QTOPIA_REPLACE_WIDGET_OVERRIDE() macros and selected as described in the Qtopia Server Widgets overview.


Macro Documentation

QTOPIA_DEMAND_TASK ( TaskName, Object )

Mark the Object as task TaskName. Only QObject derived types may be tasks. QTOPIA_DEMAND_TASK() differs from QTOPIA_TASK() in that tasks installed using this macro are automatically marked as "demand" tasks, unless specifically overridden in the Tasks.cfg file. That is, tasks installed like this will only be instantiated on request, not during server startup.

As the QTOPIA_DEMAND_TASK() macro defines symbols, it should appear only in the implementation file of a task, and not in the header file.

QTOPIA_REPLACE_WIDGET ( AbstractWidget, ConcreteWidget )

Mark ConcreteWidget as a replacement for AbstractWidget. While AbstractWidget does not actually have to be abstract, it is generally an interface that ConcreteWidget implements. This macro should appear as part of the definition of ConcreteWidget.

For example,

    // wheelbrowserscreen.h
    class WheelBrowserScreen : public QAbstractBrowserScreen
    {
        // ...
    };

    // wheelbrowserscreen.cpp
    QTOPIA_REPLACE_WIDGET(QAbstractBrowserScreen, WheelBrowserScreen);

QTOPIA_REPLACE_WIDGET_OVERRIDE ( AbstractWidget, ConcreteWidget )

Set ConcreteWidget as the static replacement for AbstractWidget.

While as efficient as possible, use of the widget replacement system instead of explicitly instantiating concrete classes does introduce some indirection costs. For shipping software where this flexibility is not necessary, QTOPIA_REPLACE_WIDGET_OVERRIDE() can be used to force the selection of a specified ConcreteWidget. This eliminates the cost of the widget replacement system for the particular AbstractWidget by bypassing the replacement system. The macro should appear inline with the AbstractWidget declaration, and must have visibility of the ConcreteWidget's declaration.

For example,

    // qabstractbrowserscreen.h
    class QAbstractBrowserScreen : public QWidget
    {
        // ...
    };

    #include "wheelbrowserscreen.h"
    QTOPIA_REPLACE_WIDGET_OVERRIDE(QAbstractBrowserScreen, WheelBrowserScreen);

QTOPIA_REPLACE_WIDGET_WHEN ( AbstractWidget, ConcreteWidget, Feature )

Mark ConcreteWidget as a replacement for AbstractWidget. While AbstractWidget does not actually have to be abstract, it is generally an interface that ConcreteWidget implements. This macro should appear as part of the definition of ConcreteWidget.

Unless explicitly specified in the Trolltech/ServerWidgets file, a widget specified in this fashion if Feature is currently provided by Qtopia, as returned by the QtopiaFeatures::hasFeature() method.

For example,

    // touchscreendialer.h
    class TouchscreenDialerScreen : public QAbstractDialerScreen
    {
        // ...
    };

    // touchscreendialer.cpp
    QTOPIA_REPLACE_WIDGET_WHEN(QAbstractDialerScreen, TouchscreenDialerScreen, Touchscreen);

QTOPIA_STATIC_TASK ( TaskName, Function )

Install a functional task. A functional task is one that does not consist of an instantiable object, but is, instead, a simple function. Static tasks can obviously not provide interfaces.

TaskName should be set to the name of the task, and Function to the static function to call to run the task.

As the QTOPIA_STATIC_TASK() macro defines symbols, it should appear only in the implementation file of a task, and not in the header file.

QTOPIA_TASK ( TaskName, Object )

Mark the Object as task TaskName. Only QObject derived types may be tasks.

As the QTOPIA_TASK() macro defines symbols, it should appear only in the implementation file of a task, and not in the header file.

QTOPIA_TASK_INTERFACE ( ClassName )

Mark the specified QObject-derived ClassName as a task interface. Any class interface that is required to support the qtopiaTask<>() or qtopiaTasks<>() request mechanism must be marked as a task interface.

The QTOPIA_TASK_INTERFACE() macro must be used in a header file, immediately following the interface's declaration.

If the interface is not a QObject type, but rather a Qt Q_INTERFACE() style interface, use the QTOPIA_TASK_QINTERFACE() macro instead.

QTOPIA_TASK_PROVIDES ( TaskName, Interface )

Indicate that the task TaskName provides Interface, as previously declared by QTOPIA_TASK_INTERFACE. A task can provide more than one interface.

For a task to support the interface, it must either inherit directly from the interface or aggregate itself with an object that does during its construction. The QtopiaServerApplication::addAggregateObject() method can be used to aggregate a task with another object.

QTOPIA_TASK_QINTERFACE ( InterfaceName )

Mark the specified InterfaceName as a task interface. Any class interface that is required to support the qtopiaTask<>() or qtopiaTasks<>() request mechanism must be marked as a task interface.

The QTOPIA_TASK_!INTERFACE() macro must be used in a header file, immediately following the interface's declaration.

InterfaceName should be a Qt Q_INTERFACE style interface. If you want to use a QObject derived type as an interface, use the QTOPIA_TASK_INTERFACE() macro instead.


Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3