Home · All Namespaces · All Classes · Grouped Classes · Modules · Functions codeless banner

Porting Between Qtopia/Qt Extended Versions


Porting an application from one Qtopia/Qt Extended version to another depends on the source and binary compatibility between the versions.

The general rules are:

However, there are exceptions to these rules, because compatibility between releases is a compromise between improving the API to make future development effort less, and minimizing porting effort. The incompatibilities scheduled for Qtopia/Qt Extended are:

4.1.0 to 4.1.6Significant incompatibilities in many API components.
4.1.7 to 4.1.99No incompatibilities introduced.
4.2.0Significant incompatibilities in a small number of API components.
4.2.1Minor incompatibilities in a small number of API components.
4.2.2Minor incompatibilities in a small number of API components.
4.2.3No incompatibilities.
4.3.0No source incompatibilities.
SubsequentStandard compatibility rules apply.

Of course, while compatibility is not available between some versions, considerable steps, such as the information below, are taken to minimize the porting effort.

Porting from Qtopia 2

Porting an application from Qtopia 2 to any Qtopia 4 series involves changing the application code corresponding to how the API for Qtopia has changed.

Primarily, porting changes will relate to the changes in the Qt API. Qtopia/Qt Extended does not support the Qt 3 Support module, so the task of porting from Qtopia 2 to Qtopia 4 takes more work than porting from Qt 2 to Qt 4, however the key documents remain:

Porting to Qtopia 4.2.0

The API of Qtopia 4.2.0 is very similar to that of Qtopia 4.1. The most notable exception is that the Telephony APIs have been significantly updated.

Telephony API

Qtopia 4.1's Telephony API used a central QPhoneLine object, from which all telephony features were accessed. This class has been replaced with several classes for each area of telephony functionality. In particular, previous code that used QPhoneLine::query() and QPhoneLine::modify() must be modified to use methods in the classes below:

QAdviceOfChargeAdvice of charge information during a call.
QBandSelectionSelection of GSM bands - 850 MHz, 900 MHz, 1800 MHz, 1900 MHz, dual, and tri-band.
QCallBarringSettings related to call barring.
QCallForwardingSettings related to call forwarding.
QCallSettingsOther call settings: call waiting and caller ID restrictriction.
QCellBroadcastAccess to cell broadcast messages.
QGprsNetworkRegistrationNotification of GPRS registration state.
QNetworkRegistrationNotification of general network registration state, plus operator selection.
QPhoneBookAccess to phone books that are stored on a SIM.
QPhoneCallManagerMaking and receiving calls: voice, data, fax, etc.
QPhoneRfFunctionalityManipulation of the RF functionality level for selecting airplane and non-airplane modes.
QPinManagerNotification of PIN requests, and PIN management (change, lock, unlock, etc).
QPreferredNetworkOperatorsAccess to the preferred network operator list in a SIM.
QPresenceVoIP presence information.
QServiceCheckerCheck that a service was started and has sufficient resources to perform operations.
QServiceNumbersAccess to service numbers such as SMS service center and the voice mail number.
QSimFilesRaw access to files on the SIM.
QSimInfoInformation about the SIM's identity and whether or not it is currently inserted.
QSimToolkitAccess to SIM Application Toolkit features of the SIM.
QSMSReaderAccess to the incoming SMS message queue.
QSMSSenderAccess to the outgoing SMS message queue.
QSupplementaryServicesSS and USSD support for GSM networks.
QTelephonyConfigurationService configuration interface and miscellaneous settings.

Modem vendor plugins and multiplexer implementations from Qtopia 4.1 must also be updated. See the following pages for more information:

OTA SMS and WAP Push messages are now dispatched using the QDS service system. See OTA Support for more information.

Network API

The Network APIs have been extended by moving device specific information from QNetworkState to the new class QNetworkDevice. In addition QNetworkInterface (introduced by Qt 4.2) replaces QHostAddress throughout the Network API's.

The table below lists the function conversions for porting to Qtopia 4.2.0.

Qtopia 4.1.xQtopia 4.2.0
QtopiaNetwork::networkOnline()QtopiaNetwork::online(), QNetworkState::connected(), QNetworkState::disconnected()

Application Lifecycle

Qtopia applications may start in response to QCop messages or service requests. In Qtopia 4.1 and earlier, applications would start, handle these messages and then terminate unless they called QtopiaApplication::setKeepRunning(). The QtopiaApplication::setKeepRunning() API has been removed in Qtopia 4.2.0 and replaced with a more flexible "task" oriented mechanism.

The documentation for QtopiaApplication covers this new model in depth. The two most common uses of QtopiaApplication::setKeepRunning() and the appropriate replacement are:

Application is displaying UI, and the setKeepRunning() call was used to ensure that the application does not exit until the user has finished interacting with it.No replacement is necessary. Qtopia applications now continue to run automatically as long as any UI is being displayed.
Application uses setKeepRunning() to continue running to perform background processing without displaying any UI to the user.Calls to setKeepRunning() may be replaced with QtopiaApplication::registerRunningTask(). The application will exit once a corresponding QtopiaApplication::unregisterRunningTask() call is made.


Several of the QCop-related IPC classes were renamed between Qtopia 4.1.x and Qtopia 4.2.0:

Qtopia 4.1.xQtopia 4.2.0

The functionality remains essentially the same. See the documentation for the individual classes for more information.

In addition, it is recommended that code that used QCopChannel should be updated to use QtopiaChannel instead. QCopChannel still exists as part of Qt for Embedded Linux, but future versions of Qtopia may implement QtopiaChannel differently.


QContentFilter changed from a typedef of QMultiHash< QContentSet::FilterType, QString > to a new class with a different API and is no longer a member of QContentSet. Basic filters in Qtopia 4.2 are still formed of a FilterType/QString pair but are combined using the logical operators And (&) and Or (|) and can be negated using the negation (~) operator. The FilterType enum is also now a member of QContentFilter and not QContentSet, and the addCriteria() members of QContentSet take an additional argument; a QContentFilter::Operand which specifices how the new criteria should be combined with any existing criteria.

The API of QDocumentSelector has changed which has resulted in some methods being removed or replaced, the functional equivalents are listed in the table below:

Qtopia 4.1.xQtopia 4.2.0
QDocumentSelector(QString,QWidget*)QDocumentSelector::QDocumentSelector(QWidget*); setFilter(QContentFilter)
QDocumentSelector(QString,QCategoryFilter,QWidget*)QDocumentSelector::QDocumentSelector(QWidget*); setFilter(QContentFilter)
QDocumentSelector(QContentSet,QWidget*)QDocumentSelector::QDocumentSelector(QWidget*); setFilter(QContentFilter)
QDocumentSelector(QContentSet::QContentFilter,QWidget*)QDocumentSelector::QDocumentSelector(QWidget*); setFilter(QContentFilter)

The QContentId typedef has changed from a quint64 to a QPair< QtopiaDatabaseId, quint64 >.

The model() member of QContentSet has been removed, a model for a QContentSet can now by constructing a new QContentSetModel and passing a pointer to the content set as an argument.

QContent::UsageMode has been renamed QContent::Role, QContent::UsageMode has been retained as a typedef of QContent::Role for compatability but is deprecated and should not be used in new code. Likewise QContent::usageMode() has been replaced by QContent::role().


The DRM API in Qtopia 4.2 has been reworked and extended to support multiple DRM agents supporting different implementations.

QDrmContent has been simplified and no longer inherits from QContent and can only be assigned a QContent with a successful call to requestLicense(QContent). The license permission must be set separately using setPermission() prior to requesting the license and a license handover can be requested by setting the QDrmContent::Handover activation option with setLicenseOptions(). The assigned QContent can be accessed using QDrmContent::content().

Some of QDrmContent's members have also been renamed or relocated to QDrmRights or QContent, the table below lists the conversions for porting to Qtopia 4.2:

Qtopia 4.1.xQtopia 4.2.0

The DRM agent integration layer from Qtopia 4.1 has been fully replaced. In Qtopia 4.1 this consisted of a single class QDrmContentAgent which specifically targeted OMA DRM v1 and only supported a single agent. Qtopia 4.2 introduces a more generic plugin based system which replaces QDrmContentAgent, the details of which are available in the DRM Agent Integration guide.


Some lower-level functionality has been moved from parts of Qtopia's libraries into libqtopiabase. All Qtopia projects implicitly depend on this library but if you are not using Qt-style includes (See Qtopia 4 Headers) you may have compile problems. In particular several headers that could previously be included with <qtopia/header.h> are now only available via <header.h> (or <qtopiabase/header.h> in cases where the header has a conflicting name).

Porting to Qtopia 4.2.1

The QObexPushService::aboutToDelete signal has been removed. Please use the QObject::destroyed() signal instead.

Porting to Qtopia 4.2.2


Signal level API

Qtopia 4.2.2 introduced QSignalSource to manage signal level information. To enable multiple signal sources Qtopia uses the concept of a virtual default signal that is mapped to the most appropriate actual signal. This change means that the value space for the signal level information has changed from /Telephony/Status/SignalLevel/modem to /Hardware/Accessories/SignalSources/DefaultSignal/Values/SignalStrength

This change effected every theme that provided signal quality information.

Qpk packages

Qpk packages built with 4.2.2 will have a Qtopia version field included in the package's control file, which contains metainformation concerning the package. Package Manager requires packages to have this field filled in otherwise, it will not install the package; as a result packages built prior to 4.2.2 won't install with Qtopia 4.2.2.

If a package built prior to 4.2.2 needs to be installed, there is a workaround which is to untar the qpk, edit the control file to include the line, "QtopiaVersion: 4.2.2", retar the qpk and then remake the packages.list or qpd file on the server. This is not a recommended step, if for no other reason than the binary incompatibilities introduced in 4.2.2.

Porting to Qtopia 4.2.3

Telephony API

The QCBSMessage::Language enumeration has three new language values: Hungarian, Polish, and Unspecified, to improve conformance with 3GPP TS 23.038. Pre-4.2.3 code can check for such messages by casting the result of QCBSMessage::language() to int and comparing against 13 (for Hungarian), 14 (for Polish), or 15 (for Unspecified).

Bluetooth API

Accessory API

The QHardwareManager class has been extended and supports focusing onto a particular accessory interface type. Previously this class provided change notifications for all accessory interface types at the same time which required some processing in order to determine which particular type just changed.

Network configuration file format

The network configuration file format has slightly been changed to allow direct assignment of particular Linux network interface names to Qtopia configurations. This effects the following configuration file entries:

A detailed description of the file format can be found in the Network Services documentation.

Porting to Qtopia 4.2.5

Bluetooth API

QBluetoothRemoteDeviceDialogFilter's copy constructor and assignment operator have been made private, and QBluetoothRemoteDeviceDialog::getRemoteDevice() and QBluetoothRemoteDeviceDialog::setFilter() now accept pointers to QBluetoothRemoteDeviceDialogFilter objects rather than references.

Porting to Qtopia 4.3.0

Accessory API

Due to the removal of certain accessories (see above) QPhoneProfile was changed:

More details about the change can be found in the class documentation for QPhoneProfile.


Qt 4.3 introduced SSL support based on OpenSSL. In the process the new class QSslSocket has been added to Qt 4.3. Qtopia 4.3 makes use of this new class and subsequently the previous solution QtSslSocket has been removed from libqtopiacomm.


In Qtopia 4.2, there is a QWizard class in the Qtopia libraries. In Qtopia 4.3 and subsequent releases, a rewritten class of the same name is part of the Qt for Embedded Linux libraries.

When porting code that used the 4.2 QWizard, the most significant difference is that now pages in the wizard are of type QWizardPage (they were just any QWidget in 4.2). Your compiler will report clearly where you need to change QWidget to QWizardPage.

Approximate equivalents for methods are:

Qtopia 4.2Qtopia 4.3
aboutToShowPage(int) (signal)QWizard::initializePage(int) (virtual)
setNextEnabled()Manage the QWizard::button(QWizard::NextButton) directly
setPrevEnabled()Manage the QWizard::button(QWizard::BackButton) directly
connectPageEnabler()QWizard::nextId() (virtual) or QWizardPage::nextId() (virtual)
setAppropriate()QWizard::nextId() (virtual) or QWizardPage::nextId() (virtual)
showPage()QWizard::restart(), QWizard::next() or QWizardPage::back()


The following functions no longer act on QOccurrenceModel

Additionally the signal fetchCompleted() is no longer emitted from the model. It is also no longer necessary to explicitly call rebuildCache() as this will be handled automatically by the model.

Qtopia PIM Delegates

The addition of the QPimDelegate class means that QTaskDelegate and QContactDelegate are no longer based on QAbstractItemDelegate. Instead, they are based on QPimDelegate and now have a different appearance.


The QtopiaSendVia::sendFile() function that accepted a filename string, a MIME type string and a bool in 4.2 now accepts an additional QString argument for the file description.


The following functions have been removed:


The QIrServer::ServerError enumeration has been removed. The QIrSocket::SocketError enumeration is used instead. The error() function has been renamed to serverError()

Qtopia Namespace

The following function has been removed.


The QBluetoothAbstractServer::ServerError enumeration has been removed. The QBluetoothAbstractSocket::SocketError enumeration is used instead. The error() function has been renamed to serverError()


The QBluetoothAbstractSocket::BindError enumeration value has been removed.

OBEX API and OBEX-related classes in Bluetooth and IrDA APIs

QObexSocket and its subclasses, QBluetoothObexSocket and QIrObexSocket, have been removed. In Qtopia 4.2, these classes provided a way to specify the transport to be used for a QObexPushClient or QObexPushService; in Qtopia 4.3, they are no longer necessary as QObexPushClient and QObexPushService now accept QIODevice pointers instead of QObexSocket pointers for this purpose. This means the developer can use any QIODevice subclass such as QBluetoothRfcommSocket, QIrSocket or QTcpSocket to specify the transport layer for a OBEX Object Push client or service.

These changes also mean that QObexServer, QBluetoothObexServer and QIrObexServer are no longer necessary and have been removed. The developer can directly use QBluetoothRfcommServer and QIrServer instead.

To port existing code to the 4.3 API:

TaskQtopia 4.2Qtopia 4.3
To connect to a remote Bluetooth or IrDA device and run an OBEX Object Push client or service.Use QBluetoothObexSocket or QIrObexSocket to construct a QObexPushClient or QObexPushService.Use QBluetoothRfcommSocket or QIrSocket to construct a QObexPushClient or QObexPushService.
To accept a client connection from a remote Bluetooth or IrDA device and run an OBEX Object Push client or service.Run a server using QBluetoothObexServer or QIrObexServer, and use the nextPendingConnection() to construct a QObexPushClient or QObexPushService.Run a server using QBluetoothRfcommServer or QIrServer, and use the nextPendingConnection() to construct a QObexPushClient or QObexPushService.

Changes to the QObexPushClient API:

Changes to the QObexPushService API:

VoIP Integration

In Qtopia 4.2 and earlier, VoIP stacks could be integrated into Qtopia using a socket-based protocol. Qtopia 4.3.0 still supports the socket-based protocol, but it is considered deprecated and will be removed in Qtopia 4.3.1.

VoIP stacks should now implement a QTelephonyService handler. See the VoIP Integration Guide for more information. The source code for the sipagent program provides an example of how to do this for SIP-based VoIP stacks.

The VoIP API's for QPhoneCallProvider and QNetworkRegistration are reasonably stable at this point. The QPresence API is preliminary and may be altered in a future version of Qtopia to handle richer presence information than is currently possible.

QDawg files

The bit arrangement of QDawg::Node has been optimized. You will need to regenerate dawg files (this happens automatically during normal Qtopia build process).

Icons Directory Layout and Theming

In previous versions of Qtopia the icons/ directory contained subdirectories named 16x16, 22x22, scalable, and so on.

Qtopia 4.3 does include these directories in the source, however at installation these directories are stripped. A single icon is installed by make install in the icons/ directory. See Images and Icons for more information.

Theme packages setting the IconPath must also ensure that the replacement icons follow the new layout.

Porting to Qtopia 4.3.1

Server file changes

The position of some server source code files has changed so that source files with common functionality are grouped within same subdirectories. Except for some bug fixing related changes the files in the new locations are identical to their old counterparts.

Old fileNew file

QtopiaIpcAdaptor changes

In previous versions of Qtopia, a class that inherited from QtopiaIpcAdaptor that used the connect() method without qualification would get QtopiaIpcAdaptor::connect() instead of QObject::connect(). This would sometimes cause hard to find problems where the user intended to connect to a regular signal but was actually connecting to an IPC message.

The MESSAGE(x) macro in qtopiaipcadaptor.h has been changed so that it is not the same as the SIGNAL(x) macro. This allows QtopiaIpcAdaptor::connect() to correctly determine when it should fall back to QObject::connect() when called from a subclass of QtopiaIpcAdaptor.

From 4.3.1 onwards it is required that MESSAGE(x) be used when connecting to an IPC message rather than an actual signal. The "No such signal" error may be generated if previous code used SIGNAL(x) to refer to an IPC message.

This change introduces a slight binary incompatibility between 4.3.0 and 4.3.1: third-party code that uses QtopiaIpcAdaptor::connect() will need to be recompiled to pick up the new definition for MESSAGE(x).

Names changes

The RunningApplicationsViewItem has been renamed to TaskManagerEntry.

VoIP Integration

The socket-based protocol for VoIP integration is no longer supported from Qtopia 4.3.1 onwards.

QMailStore changes

In 4.3.0, the QMailStore class provided overloads of the QMailStore::queryFolders() and QMailStore::queryMessages() functions, so that the filter key and sort key parameters could each be independently provided or omitted by the caller.

In 4.3.1, the overloads have been removed, and default parameters are used instead. Third-party code that uses the queryFolders(const QMailFolderSortKey&) or queryMessages(const QMailMessageSortKey&) overloads to retrieve all records in a particular order, must be changed to supply a default-constructed filter key preceding the sort key.

Porting to Qtopia 4.3.2

Server file changes

The position of some server source code files has changed so that source files with common functionality are grouped within same subdirectories. Except for some bug fixing related changes the files in the new locations are identifical to their old counter parts.

Old fileNew file
server/phone/phonethemeview.{cpp|h}server/phone/themecontrol/serverthemeview.{cpp|h} (NAME CHANGED)

Porting to Qtopia/Qt Extended 4.4


Qtopia has been renamed to Qt Extended. This name change does not affect any class or function names. Binary compatibility to previous Qtopia releases is retained. However most parts of the documentation now refer to Qt Extended rather then Qtopia.

QSpeedDial changes

QSpeedDial::find() now requires the caller to delete the QtopiaServiceDescription when they are done with it. This change does not create binary or source incompatibility, but code that uses QSpeedDial::find() may now have undesirable memory leaks.

Server changes

The HomescreenWidgets class has been replaced by the UIFactory class which provides the same functionality.

The HomeScreenControl class, providing a singleton wrapper for a QAbstractHomeScreen instance, has been removed. The QAbstractHomeScreen class directly supports the singleton pattern which removed the need for HomeScreenControl. For more details about singleton support for abstract server widgets see the Server Widget documentation.

The PhoneBrowser class has been renamed to GridBrowser.

QContent changes

The name of MP3 files are now derived from the file name and not the title in ID3 tags, the title is instead stored in the "Title" property of the QContent. This means that views constructed with QContentSetModel now display the file name of songs and not the title. A view which displays the title can still be created by inheriting from QContentSetModel and overriding data() to return the title instead of the name.

DBMigrate changes

The dbmigrate application has been deprecated and replaced with a plug-in of the same name. The plug-in is run in process and as such does not suffer the same synchronization and time-out issues as the DBMigrate service did.

This isn't expected to effect non Qtopia code but if required the command line and service interfaces of the dbmigrate application are still available from a new project in src/tools/dbmigrateservice.

This change also obsoletes the DBMigrate server task which has been removed from the server. Any references to DBMigrate in Tasks.cfg files are now obsolete and should be removed.

Source tree changes

The directories containing the source code of several applications have been renamed to make the structure of the source tree more consistent. The old and new directory names are shown in the following table.

ApplicationOld LocationNew Location

Safe Execution Environment changes

The Safe Execution Environment(SXE) configure option is no longer on by default. SXE must now be explicitly turned on by passing -sxe to configure.

Porting to Qtopia/Qt Extended 4.4.1

The most significant change here is the build system. See Porting to QBuild.

Porting to Qtopia/Qt Extended 4.4.2

Resources have been moved into the project that uses them. This has most impact on devices which previously were able to override certain config files by placing them in devices/device/etc. As a result of this change, the files must be placed in devices/device/src/project/etc instead. While this makes it clearer what project a configuration file belongs to it requires moving files for existing devices created with 4.4.1 and earlier in mind. This burden has been eased in 4.4.3, which allows files in etc to be located in devices/device/etc or the newer devices/device/src/project/etc.

Copyright © 2009 Nokia Trademarks
Qt Extended 4.4.3