Deprecation guide (8th April 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)
    dtors for a number of classes have been removed, since they were empty and will always be empty.
    QContactDetails now use Latin1 strings as the keys for values (and for their definition name).  QString keys will still work.

    Several classes have been adjusted so that they are now "small" (sizeof(class) <= sizeof(void*)) - this means
    that lists/hashes/maps of them will be more efficient, but code needs recompilation.

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
        Constructors are now explicit.
    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:
    The ctors have been marked explicit, to avoid accidentally invoking a conversion from const char* or QString.
    The keys for all values (and definition name) are now stored as latin1 strings (const char*), resulting in
    significant memory and runtime savings.  QStrings used as keys will still work, but be converted to latin1
    first.

    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

-----------------------
Deprecated Guide (19th April 2010)

QContact:
    - QContact::detailWithAction(const QString& actionName) is deprecated
    - QContact::detailsWithAction(const QString& actionName) is deprecated
    -> these are replaced by QContact::detail(s)WithAction(QAction* actionPtr)

QContactManager:
    - QContactManager::synthesizedDisplayLabel(const QContact& contact) is deprecated
    -> replaced by QContactManager::synthesizedContactDisplayLabel(const QContact& contact)

QContactManagerEngine:
    - functions no longer pure virtual.

QContactDetailDefinitionRemoveRequest:
    - QContactDetailDefinitionRemoveRequest::setDefinitionNames(const QString& contactType, const QStringList& definitionNames)) is deprecated
    -> replaced by QContactDetailDefinitionRemoveRequest::setContactType(const QString& contactType) + QContactDetailDefinitionRemoveRequest::setDefinitionNames(const QStringList& definitionNames).