|
Home · All Classes · Grouped Classes · Annotated · Functions | |
Porting an application from one Qtopia 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 are:
| Version | Compatiblity |
|---|---|
| 4.1.0 to 4.1.6 | Significant incompatibilities in many API components. |
| 4.1.7 to 4.1.99 | No incompatibilities introduced. |
| 4.2.0 | Significant incompatibilities in a small number of API components. |
| 4.2.1 | Minor incompatibilities in a small number of API components. |
| 4.2.2 | Minor incompatibilities in a small number of API components. |
| 4.2.3 | No incompatibilities. |
| 4.3.0 | No source incompatibilities. |
| Subsequent | Standard 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 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 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:
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.
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:
| Interface | Description |
|---|---|
| QAdviceOfCharge | Advice of charge information during a call. |
| QBandSelection | Selection of GSM bands - 850 MHz, 900 MHz, 1800 MHz, 1900 MHz, dual, and tri-band. |
| QCallBarring | Settings related to call barring. |
| QCallForwarding | Settings related to call forwarding. |
| QCallSettings | Other call settings: call waiting and caller ID restrictriction. |
| QCellBroadcast | Access to cell broadcast messages. |
| QGprsNetworkRegistration | Notification of GPRS registration state. |
| QNetworkRegistration | Notification of general network registration state, plus operator selection. |
| QPhoneBook | Access to phone books that are stored on a SIM. |
| QPhoneCallManager | Making and receiving calls: voice, data, fax, etc. |
| QPhoneRfFunctionality | Manipulation of the RF functionality level for selecting airplane and non-airplane modes. |
| QPinManager | Notification of PIN requests, and PIN management (change, lock, unlock, etc). |
| QPreferredNetworkOperators | Access to the preferred network operator list in a SIM. |
| QPresence | VoIP presence information. |
| QServiceChecker | Check that a service was started and has sufficient resources to perform operations. |
| QServiceNumbers | Access to service numbers such as SMS service center and the voice mail number. |
| QSimFiles | Raw access to files on the SIM. |
| QSimInfo | Information about the SIM's identity and whether or not it is currently inserted. |
| QSimToolkit | Access to SIM Application Toolkit features of the SIM. |
| QSMSReader | Access to the incoming SMS message queue. |
| QSMSSender | Access to the outgoing SMS message queue. |
| QSupplementaryServices | SS and USSD support for GSM networks. |
| QTelephonyConfiguration | Service 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.
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.x | Qtopia 4.2.0 |
|---|---|
| QNetworkState::addess() | QNetworkDevice::address() |
| QNetworkState::interfaces() | QNetworkState::availableNetworkDevices() |
| QtopiaNetwork::networkOnline() | QtopiaNetwork::online(), QNetworkState::connected(), QNetworkState::disconnected() |
| QtopiaNetwork::shutdownNetwork() | QtopiaNetwork::shutdown() |
| QtopiaNetwork::toType() | QNetworkState::deviceType() |
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:
| Use | Replacement |
|---|---|
| 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.x | Qtopia 4.2.0 |
|---|---|
| QCopObject | QtopiaIpcAdaptor |
| QCopEnvelope | QtopiaIpcEnvelope |
| QCopService | QtopiaService |
| QCopServiceRequest | QtopiaServiceRequest |
| QCopServiceDescription | QtopiaServiceDescription |
| QCopServiceSelector | QtopiaServiceSelector |
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 Qtopia Core, 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.x | Qtopia 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) |
| setCategoryFilter(QCategoryFilter) | setDefaultCategories(QStringList) |
| categoryFilter() | defaultCategories() |
| setNewEnabled(true) | enableOptions(QDocumentSelector::NewDocument) |
| setNewEnabled(false) | disableOptions(QDocumentSelector::NewDocument) |
| selectedDocument(false) | currentDocument() |
| setDocuments(QContentSet) | 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.x | Qtopia 4.2.0 |
|---|---|
| QDrmContent::PermissionType | QDrmRights::Permission |
| QDrmContent::permissionType() | QDrmContent::permission() |
| QDrmContent::setPermissionType(QDrmContent::PermissionType) | QDrmContent::setPermission(QDrmRights::Permission) |
| QDrmContent::rightsValid(QContent,QDrmContent::PermissionType) | QContent::permissions() |
| QDrmContent::activationOptions(QContent) | QDrmContent::canActivate(QContent) |
| QDrmContent::activate(QContent,QDrmContent::ActivationOptions) | QDrmContent::activate(QContent,QWidget*) |
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).
The QObexPushService::aboutToDelete signal has been removed. Please use the QObject::destroyed() signal instead.
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 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.
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).
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.
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.
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.
| Copyright © 2007 Trolltech | Trademarks | Qtopia 4.2.5 |