Device Synchronization

Retrieving relevant changes.

The QPimModel functions added, removed and modified are used to retrieve relevant changes for a sync. While these functions are implemented in QPimModel, it is important to use one of the subclasses, QContactModel, QAppointmentModel, or QTaskModel, in order to specify what PIM data type is to be synced.

The time used with these functions should be specified in UTC. This is because changes to the users timezone, perhaps while traveling, should impact synchronization. Generally the timestamp from the previous synchronization will be used with these functions in order to only deal with the changes between two synchronization actions. To this end these functions treat a null datetime as specifying a slow or full sync. Hence passing a null for added will return all records, and passing a null for modified or removed will return no records. For any single timestamp, a record will appear only in one of the added, removed, or modified results.

It is also important to note that the filtering applied to a model, be it for completed tasks or contacts from a certain data source, also apply to the added, modified and removed functions.

    void MyTasksSync::fetchChangesSince(const QDateTime &since)
    {
        QList<QUniqueId> changes = model->added(since);

        foreach(const QUniqueId &id, changes) {
            QTask t = model->task(id);
            mySendAddedTask(t);
        }

        changes = model->removed(since);
        foreach(const QUniqueId &id, changes) {
            mySendRemovedTask(id);
        }

        changes = model->modified(since);
        foreach(const QUniqueId &id, changes) {
            QTask t = model->task(id);
            mySendModifiedTask(t);
        }
    }

Tracking any identifier mapping, the last sync time and other synchronization bookkeeping is the responsibility of the protocol implementation. If an implementation of the above behavior is required its likely Desktop Synchronization will be a preferred starting point.

        QTaskModel tasks;
        QContactModel contacts;

        // incorrect
        QDateTime syncTime = QDateTime::currentDateTime();
        tasks.startSyncTransaction(syncTime);
        contacts.startSyncTransaction(syncTime);
        // modify tasks
        // modify contacts
        tasks.commitSyncTransaction();
        contacts.commitSyncTransaction();

        // correct
        QDateTime syncTime = QDateTime::currentDateTime().toUTC();
        tasks.startSyncTransaction(syncTime);
        // modify tasks
        tasks.commitSyncTransaction();
        contacts.startSyncTransaction(syncTime);
        // modify contacts
        contacts.commitSyncTransaction();