--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/qtcontactsmobility/DEPRECATION Mon May 03 12:24:20 2010 +0300
@@ -0,0 +1,233 @@
+Deprecation guide (23 March 2010)
+=================
+Known source breaks:
+ There are a number of source breaks that nearly all just affect engine writers - marked with [!] in this document. Largely
+ these fall into two classes - 1) interface functions becoming pure virtual and 2) return type changing.
+
+ Of these categories, client code is only somewhat likely to encounter the second case (QContactRelationshipFilter::relatedContactRole
+ changed return type from QContactRelationshipFilter::Role to QContactRelationship::Role). You can search and replace this
+ change, however. This function is usually more useful to engine writers, though.
+
+ The other category of break in this release affects engine writers. All engines that were in the
+ qtmobility repository have been updated.
+
+ The QContactManagerEngine interface has been made largely pure virtual to avoid problems when implementing an engine
+ and not using the correct signature (or when the interface changes). In addition, any non const refs (e.g.
+ QContactManager::Error &) have been replaced with a pointer, or with explicit functions (in QContactChangeset).
+
+New classes:
+ QContactThumbnail [Detail - QImage for list view purposes]
+ QContactRingtone [Detail - audio/video ringtones]
+ QContactPresence [Detail - presence information from a service]
+ QContactGlobalPresence [Detail - aggregated presence]
+ QContactTag [Detail - Tag/category for a contact]
+
+ QContactFetchHint [Hints for fetching contacts - details, relationships, blobs etc]
+
+New functionality:
+ qHash for QContact, QContactActionDescriptor, QContactDetail, QContactId, QContactRelationship, QVersitDocument, QVersitProperty
+ qDebug streaming for QContact, QContactDetail, QContactId, QContactRelationship, QVersitDocument, QVersitProperty
+ operator< for QContactId, QContactActionDescriptor
+
+General changes:
+ Q_DECLARE_LATIN1_LITERAL -> Q_DECLARE_LATIN1_CONSTANT and Latin1Literal -> QLatin1Constant - Don't use the old ones.
+ QContactRelationshipFilter::Role moved to QContactRelationship::Role (affects all places that deal with relationships)
+ QContactLocalId - definition moved to qcontactid.h from qtcontactsglobal.h (old header includes new one right now)
+
+QContact:
+ Deprecated members:
+ setRelationshipOrder() [No replacement]
+ relationshipOrder() [No replacement]
+ relatedContacts(... taking a QCRF::Role) [use relatedContacts taking a QCR::Role instead]
+
+ New members:
+ relatedContacts(... taking a QCR::Role)
+ preferredDetails() [Returns a map of detail preferences]
+
+QContactManager:
+ General changes:
+ All fetch functions taking a list of detail definitions to retrieve have been changed to use QContactFetchHint instead
+ Some functions now take a const List<T>& rather than a List<T>*
+ Functions returning a QList<QContactManager::Error> are replaced with parameters pointing to an error map to fill in
+ Deprecated members:
+ 2 x contacts(.. QStringList definitionRestrictions ..) [use contacts functions that takes QContactFetchHint instead]
+ contact(.. QStringList definitionRestrictions ..) [use contact function that takes QContactFetchHint instead]
+ removeContacts(QList<QContact>* contacts, ...) [use removeContacts(const QList<QContact>&, ...) instead]
+ 2 x relationships(.. taking a QCRF::Role ..) [use relationships functions that take QContactRelationship::Role instead]
+ QList<Error> saveRelationships(...) [use bool saveRelationships(...) instead]
+ QList<Error> removeRelationships(...) [use bool removeRelationships(...) instead]
+ QSL supportedRelationshipTypes() [use bool isRelationshipTypeSupported(QString) instead]
+ New members:
+ contact,contacts,relationships taking a QContactRelationship::Role instead
+ saveRelationships/removeRelationships taking a QMap<int, QCM::Error>* parameter instead
+ bool isRelationshipTypeSupported(const QString&) const
+ compatibleContact - given an input contact, return a contact that can be saved in this manager (by stripping unsupported fields etc)
+
+QContactManagerEngine:
+ General changes:
+ [!] There have been a large number of changes here...
+ Nearly all functions are now pure virtual and must be implemented in the engine. Default implementations exist,
+ but the engine writer must make the conscious decision to use them.
+ The QCME API is now smaller than the QCM API, and several QCM functions are now convenience wrappers around
+ QCME functions (particularly w.r.t. contact fetching)
+ The actual API changes themselves follow the QCM API (e.g. taking pointers to error map rather than returning error lists)
+ Deprecated members:
+ The updateXXXXXRequest functions now allow you to specify the request state atomically with results. The old functions are deprecated,
+ with the addition of an extra parameter at the end of the parameter list.
+
+QContactRelationshipFilter:
+ Deprecated members:
+ enum Role has been moved to QContactRelationship
+ setRelatedContactRole(QCRF::Role..) [use setRelatedContactRole(QCR::Role) instead]
+ Changed members (Source break):
+ [!] relatedContactRole now returns a QCR::Role instead of a QCRF::Role
+
+QContactFetchRequest:
+ This class has changed to use QContactFetchHint instead of the list of detail definitions
+ Deprecated members:
+ setDefinitionRestrictions [use setFetchHint() with an appropriate QContactFetchHint]
+ definitionRestrictions [use fetchHint() and retrieve the detailDefinitionHint]
+ New members:
+ fetchHint()
+ setFetchHint()
+
+QContactDetail:
+ Deprecated members:
+ preferredActions [No replacement]
+ setPreferredActions [No replacement]
+
+QContactRelationship:
+ QContactRelationshipFilter::Role enum moved here
+
+QContactActionDescriptor:
+ Constructor is now explicit, no other change
+
+QContactChangeSet:
+ Class for engine writers, some large changes:
+ Non-const refs in API deprecated - split into const accessor and insert/clear functions
+ Old and new self contact API changed to explicit function rather than QPair
+
+QContactAddress:
+ DefinitionName (value changed from StreetAddress -> Address)
+
+QContactAvatar:
+ The avatar class has been split into 3 classes (QContactAvatar, QContactThumbnail and QContactRingtone),
+ and individual fields rather than subtypes with a single value.
+
+ Deprecated members:
+ FieldAvatar [Use QContactAvatar::FieldImageUrl or FieldVideoUrl]
+ FieldAvatarPixmap [Use QContactThumbnail::Thumbnail]
+ FieldSubType [No replacement]
+ SubTypeImage [No replacement, image stored in QContactThumbnail::thumbnail() or QContactAvatar::imageUrl()]
+ SubTypeVideo [No replacement, stored in QContactAvatar::videoUrl()]
+ SubTypeTexturedMesh [No replacement]
+ SubTypeAudioRingtone [No replacement, stored in QContactRingtone::audioRingtone()]
+ SubTypeVideoRingtone [No replacement, stored in QContactRingtone::videoRingtone()]
+ avatar() [Use QContactAvatar::imageUrl() or QContactAvatar::videoUrl()]
+ setAvatar() [Use QContactAvatar::setImageUrl() or QContactAvatar::setVideoUrl()]
+ pixmap() [Use QContactThumbnail::thumbnail() - QImage instead of QPixmap]
+ setPixmap() [Use QContactThumbnail::setThumbnail() - QImage instead of QPixmap]
+ subType() [No replacement - explicit fields instead of subtypes
+ setSubType() [No replacement - explicit fields instead of subtypes
+
+ New members:
+ FieldImageUrl
+ FieldVideoUrl
+ void setImageUrl(const QUrl& imageUrl);
+ QUrl imageUrl() const;
+ void setVideoUrl(const QUrl& videoUrl);
+ QUrl videoUrl() const;
+
+QContactOrganization:
+ Deprecated members:
+ FieldLogo [Use QContactOrganization::FieldLogoUrl]
+ logo() [Use logoUrl() instead]
+ setLogo() [Use setLogoUrl() instead]
+
+ New members:
+ FieldLogoUrl
+ void setLogoUrl();
+ QUrl logoUrl();
+
+QContactPhoneNumber:
+ Deprecated members:
+ SubTypeFacsimile [Use SubTypeFax instead]
+
+ New members:
+ SubTypeFax
+
+QContactOnlineAccount:
+ General:
+ Presence information has been removed from here and put into QContactPresence.
+ QContactPresence details are expected to be linked to this via linkedDetailUri();
+ Deprecated members:
+ FieldPresence [Use QContactPresence::FieldPresenceState]
+ FieldNickname [Use QContactPresence::FieldNickname]
+ FieldStatusMessage [Use QContactPresence::FieldStatusText or FieldCustomMessage]
+ PresenceAvailable [Use QContactPresence::PresenceAvailable - enum, not string constant]
+ PresenceHidden [Use QContactPresence::PresenceHidden - enum, not string constant]
+ PresenceAway [Use QContactPresence::PresenceAway - enum, not string constant]
+ PresenceBusy [Use QContactPresence::PresenceBusy - enum, not string constant]
+ PresenceExtendedAway [Use QContactPresence::PresenceExtendedAway - enum, not string constant]
+ PresenceOffline [Use QContactPresence::PresenceOffline - enum, not string constant]
+ PresenceUnknown [Use QContactPresence::PresenceUnknown - enum, not string constant]
+ setPresence() [Use QContactPresence::setPresenceState()]
+ presence() [Use QContactPresence::presenceState()]
+ setNickname() [Use QContactPresence::setNickname()]
+ nickname() [Use QContactPresence::nickname()]
+ setStatusMessage() [Use QContactPresence::setPresenceStateText() or setCustomMessage()]
+ statusMessage() [Use QContactPresence::presenceStateText() or customMessage()]
+
+QContactPresence:
+ General:
+ This deprecated class header was left in the tree for a while, but not included in the
+ grouped header files, or compiled or linked. Now it has been resurrected.
+ Previous code (if any) that was using it will most likely break.
+ QContactOnlineAccount previously held presence information, and that information will
+ now be held here, and linked via linkedDetailUri() instead.
+
+QVersitContactExporter:
+ General:
+ Added simple error reporting
+ Changed to be more consistent with contacts
+ Deprecated members:
+ QList<QVD> exportContacts() [use bool exportContacts(contacts, doctype), and documents()]
+ New members:
+ QList<QVD> documents() [result of export operation]
+ QMap<int, Error> errors() [errors in export operation]
+ bool exportContacts(QList<QC>, QVD::DocType) [do export]
+
+QVersitContactImporter:
+ General:
+ Added simple error reporting
+ Changed to be more consistent with contacts
+ Deprecated members:
+ QList<QC> importContacts(QList<QVD>) [use importDocuments(QList<QVD>), and contacts() instead]
+ New members:
+ QList<QC> contacts() [result of import operation]
+ QMap<int, Error> errors() [errors in import operation]
+ bool importDocuments(const QList<QVD>&) [do import]
+
+QVersitDocument:
+ Added ctor with versit document type parameter
+
+QVersitProperty:
+ New members:
+ enum for semantic type of value (plain, compound, list, binary, versit document)
+ setter/getter for above - intended to be used by QVersitReader/QVersitWriter
+
+QVersitReader:
+ General:
+ Added capability of reading from bytearray directly (no QBuffer needed)
+ Added ctors with iodevice & bytearray for source
+ startReading() & cancel() are now slots
+ waitForFinished() is now an invokable too
+ Deprecated members:
+ resultsAvailable(QList<QVD>) signal [use resultsAvailable() and results() separately]
+
+QVersitWriter:
+ General:
+ Added capability of writing directly to a qbytearray
+ Added ctors with iodevice and bytearray for destination
+ startWriting() and cancel() are now slots
+ waitForFinished() is now an invokable