1 Deprecation guide (23 March 2010)

     2 =================

     3 Known source breaks:

     4     There are a number of source breaks that nearly all just affect engine writers - marked with [!] in this document.  Largely

     5     these fall into two classes - 1) interface functions becoming pure virtual and 2) return type changing.

     6 

     7     Of these categories, client code is only somewhat likely to encounter the second case (QContactRelationshipFilter::relatedContactRole

     8     changed return type from QContactRelationshipFilter::Role to QContactRelationship::Role).  You can search and replace this

     9     change, however.  This function is usually more useful to engine writers, though.

    10 

    11     The other category of break in this release affects engine writers.  All engines that were in the

    12     qtmobility repository have been updated.

    13 

    14     The QContactManagerEngine interface has been made largely pure virtual to avoid problems when implementing an engine

    15     and not using the correct signature (or when the interface changes).  In addition, any non const refs (e.g.

    16     QContactManager::Error &) have been replaced with a pointer, or with explicit functions (in QContactChangeset).

    17 

    18 New classes:

    19     QContactThumbnail       [Detail - QImage for list view purposes]

    20     QContactRingtone        [Detail - audio/video ringtones]

    21     QContactPresence        [Detail - presence information from a service]

    22     QContactGlobalPresence  [Detail - aggregated presence]

    23     QContactTag             [Detail - Tag/category for a contact]

    24 

    25     QContactFetchHint       [Hints for fetching contacts - details, relationships, blobs etc]

    26 

    27 New functionality:

    28     qHash for QContact, QContactActionDescriptor, QContactDetail, QContactId, QContactRelationship, QVersitDocument, QVersitProperty

    29     qDebug streaming for QContact, QContactDetail, QContactId, QContactRelationship, QVersitDocument, QVersitProperty

    30     operator< for QContactId, QContactActionDescriptor

    31 

    32 General changes:

    33     Q_DECLARE_LATIN1_LITERAL -> Q_DECLARE_LATIN1_CONSTANT and Latin1Literal -> QLatin1Constant - Don't use the old ones.

    34     QContactRelationshipFilter::Role moved to QContactRelationship::Role (affects all places that deal with relationships)

    35     QContactLocalId - definition moved to qcontactid.h from qtcontactsglobal.h (old header includes new one right now)

    36 

    37 QContact:

    38     Deprecated members:

    39         setRelationshipOrder()  [No replacement]

    40         relationshipOrder()     [No replacement]

    41         relatedContacts(... taking a QCRF::Role)    [use relatedContacts taking a QCR::Role instead]

    42 

    43     New members:

    44         relatedContacts(... taking a QCR::Role)

    45         preferredDetails()                          [Returns a map of detail preferences]

    46 

    47 QContactManager:

    48     General changes:

    49         All fetch functions taking a list of detail definitions to retrieve have been changed to use QContactFetchHint instead

    50         Some functions now take a const List<T>& rather than a List<T>*

    51         Functions returning a QList<QContactManager::Error> are replaced with parameters pointing to an error map to fill in

    52     Deprecated members:

    53         2 x contacts(.. QStringList definitionRestrictions ..)  [use contacts functions that takes QContactFetchHint instead]

    54         contact(.. QStringList definitionRestrictions ..)       [use contact function that takes QContactFetchHint instead]

    55         removeContacts(QList<QContact>* contacts, ...)          [use removeContacts(const QList<QContact>&, ...) instead]

    56         2 x relationships(.. taking a QCRF::Role ..)            [use relationships functions that take QContactRelationship::Role instead]

    57         QList<Error> saveRelationships(...)                     [use bool saveRelationships(...) instead]

    58         QList<Error> removeRelationships(...)                   [use bool removeRelationships(...) instead]

    59         QSL supportedRelationshipTypes()                        [use bool isRelationshipTypeSupported(QString) instead]

    60     New members:

    61         contact,contacts,relationships taking a QContactRelationship::Role instead

    62         saveRelationships/removeRelationships taking a QMap<int, QCM::Error>* parameter instead

    63         bool isRelationshipTypeSupported(const QString&) const

    64         compatibleContact - given an input contact, return a contact that can be saved in this manager (by stripping unsupported fields etc)

    65 

    66 QContactManagerEngine:

    67     General changes:

    68         [!] There have been a large number of changes here...

    69         Nearly all functions are now pure virtual and must be implemented in the engine.  Default implementations exist,

    70         but the engine writer must make the conscious decision to use them.

    71         The QCME API is now smaller than the QCM API, and several QCM functions are now convenience wrappers around

    72         QCME functions (particularly w.r.t. contact fetching)

    73         The actual API changes themselves follow the QCM API (e.g. taking pointers to error map rather than returning error lists)

    74     Deprecated members:

    75         The updateXXXXXRequest functions now allow you to specify the request state atomically with results.  The old functions are deprecated,

    76         with the addition of an extra parameter at the end of the parameter list.

    77 

    78 QContactRelationshipFilter:

    79     Deprecated members:

    80         enum Role has been moved to QContactRelationship

    81         setRelatedContactRole(QCRF::Role..)               [use setRelatedContactRole(QCR::Role) instead]

    82     Changed members (Source break):

    83         [!] relatedContactRole now returns a QCR::Role instead of a QCRF::Role

    84 

    85 QContactFetchRequest:

    86     This class has changed to use QContactFetchHint instead of the list of detail definitions

    87     Deprecated members:

    88         setDefinitionRestrictions           [use setFetchHint() with an appropriate QContactFetchHint]

    89         definitionRestrictions              [use fetchHint() and retrieve the detailDefinitionHint]

    90     New members:

    91         fetchHint()

    92         setFetchHint()

    93 

    94 QContactDetail:

    95     Deprecated members:

    96         preferredActions                  [No replacement]

    97         setPreferredActions                 [No replacement]

    98 

    99 QContactRelationship:

   100     QContactRelationshipFilter::Role enum moved here

   101 

   102 QContactActionDescriptor:

   103     Constructor is now explicit, no other change

   104 

   105 QContactChangeSet:

   106     Class for engine writers, some large changes:

   107     Non-const refs in API deprecated - split into const accessor and insert/clear functions

   108     Old and new self contact API changed to explicit function rather than QPair

   109 

   110 QContactAddress:

   111     DefinitionName (value changed from StreetAddress -> Address)

   112 

   113 QContactAvatar:

   114     The avatar class has been split into 3 classes (QContactAvatar, QContactThumbnail and QContactRingtone),

   115     and individual fields rather than subtypes with a single value.

   116 

   117     Deprecated members:

   118         FieldAvatar             [Use QContactAvatar::FieldImageUrl or FieldVideoUrl]

   119         FieldAvatarPixmap       [Use QContactThumbnail::Thumbnail]

   120         FieldSubType            [No replacement]

   121         SubTypeImage            [No replacement, image stored in QContactThumbnail::thumbnail() or QContactAvatar::imageUrl()]

   122         SubTypeVideo            [No replacement, stored in QContactAvatar::videoUrl()]

   123         SubTypeTexturedMesh     [No replacement]

   124         SubTypeAudioRingtone    [No replacement, stored in QContactRingtone::audioRingtone()]

   125         SubTypeVideoRingtone    [No replacement, stored in QContactRingtone::videoRingtone()]

   126         avatar()                [Use QContactAvatar::imageUrl() or QContactAvatar::videoUrl()]

   127         setAvatar()             [Use QContactAvatar::setImageUrl() or QContactAvatar::setVideoUrl()]

   128         pixmap()                [Use QContactThumbnail::thumbnail() - QImage instead of QPixmap]

   129         setPixmap()             [Use QContactThumbnail::setThumbnail() - QImage instead of QPixmap]

   130         subType()               [No replacement - explicit fields instead of subtypes

   131         setSubType()            [No replacement - explicit fields instead of subtypes

   132 

   133     New members:

   134         FieldImageUrl

   135         FieldVideoUrl

   136         void setImageUrl(const QUrl& imageUrl);

   137         QUrl imageUrl() const;

   138         void setVideoUrl(const QUrl& videoUrl);

   139         QUrl videoUrl() const;

   140 

   141 QContactOrganization:

   142     Deprecated members:

   143         FieldLogo               [Use QContactOrganization::FieldLogoUrl]

   144         logo()                  [Use logoUrl() instead]

   145         setLogo()               [Use setLogoUrl() instead]

   146 

   147     New members:

   148         FieldLogoUrl

   149         void setLogoUrl();

   150         QUrl logoUrl();

   151 

   152 QContactPhoneNumber:

   153     Deprecated members:

   154         SubTypeFacsimile        [Use SubTypeFax instead]

   155 

   156     New members:

   157         SubTypeFax

   158 

   159 QContactOnlineAccount:

   160     General:

   161         Presence information has been removed from here and put into QContactPresence.

   162         QContactPresence details are expected to be linked to this via linkedDetailUri();

   163     Deprecated members:

   164         FieldPresence           [Use QContactPresence::FieldPresenceState]

   165         FieldNickname           [Use QContactPresence::FieldNickname]

   166         FieldStatusMessage      [Use QContactPresence::FieldStatusText or FieldCustomMessage]

   167         PresenceAvailable       [Use QContactPresence::PresenceAvailable - enum, not string constant]

   168         PresenceHidden          [Use QContactPresence::PresenceHidden - enum, not string constant]

   169         PresenceAway            [Use QContactPresence::PresenceAway - enum, not string constant]

   170         PresenceBusy            [Use QContactPresence::PresenceBusy - enum, not string constant]

   171         PresenceExtendedAway    [Use QContactPresence::PresenceExtendedAway - enum, not string constant]

   172         PresenceOffline         [Use QContactPresence::PresenceOffline - enum, not string constant]

   173         PresenceUnknown         [Use QContactPresence::PresenceUnknown - enum, not string constant]

   174         setPresence()           [Use QContactPresence::setPresenceState()]

   175         presence()              [Use QContactPresence::presenceState()]

   176         setNickname()           [Use QContactPresence::setNickname()]

   177         nickname()              [Use QContactPresence::nickname()]

   178         setStatusMessage()      [Use QContactPresence::setPresenceStateText() or setCustomMessage()]

   179         statusMessage()         [Use QContactPresence::presenceStateText() or customMessage()]

   180 

   181 QContactPresence:

   182     General:

   183         This deprecated class header was left in the tree for a while, but not included in the

   184         grouped header files, or compiled or linked.  Now it has been resurrected.

   185         Previous code (if any) that was using it will most likely break.

   186         QContactOnlineAccount previously held presence information, and that information will

   187         now be held here, and linked via linkedDetailUri() instead.

   188 

   189 QVersitContactExporter:

   190     General:

   191         Added simple error reporting

   192         Changed to be more consistent with contacts

   193     Deprecated members:

   194         QList<QVD> exportContacts()                   [use bool exportContacts(contacts, doctype), and documents()]

   195     New members:

   196         QList<QVD> documents()                          [result of export operation]

   197         QMap<int, Error> errors()                       [errors in export operation]

   198         bool exportContacts(QList<QC>, QVD::DocType)    [do export]

   199 

   200 QVersitContactImporter:

   201     General:

   202         Added simple error reporting

   203         Changed to be more consistent with contacts

   204     Deprecated members:

   205         QList<QC> importContacts(QList<QVD>)            [use importDocuments(QList<QVD>), and contacts() instead]

   206     New members:

   207         QList<QC> contacts()                            [result of import operation]

   208         QMap<int, Error> errors()                       [errors in import operation]

   209         bool importDocuments(const QList<QVD>&)         [do import]

   210 

   211 QVersitDocument:

   212     Added ctor with versit document type parameter

   213 

   214 QVersitProperty:

   215     New members:

   216         enum for semantic type of value (plain, compound, list, binary, versit document)

   217         setter/getter for above - intended to be used by QVersitReader/QVersitWriter

   218 

   219 QVersitReader:

   220     General:

   221         Added capability of reading from bytearray directly (no QBuffer needed)

   222         Added ctors with iodevice & bytearray for source

   223         startReading() & cancel() are now slots

   224         waitForFinished() is now an invokable too

   225     Deprecated members:

   226         resultsAvailable(QList<QVD>) signal             [use resultsAvailable() and results() separately]

   227 

   228 QVersitWriter:

   229     General:

   230         Added capability of writing directly to a qbytearray

   231         Added ctors with iodevice and bytearray for destination

   232         startWriting() and cancel() are now slots

   233         waitForFinished() is now an invokable