Address book sync client design

This page has been flagged by editors or users as needing technical review. Until it is fully reviewed, it may contain inaccurate or incorrect information.

by Richard H. Pizzarro <rhp@netscape.com>

Contents

• Overview
• Client Side Sync Logic
• Public Interfaces

There is an component available in the mozilla tree for performing synchronization operations against a server based address book. The general architecture for the sync component is the following:

The client synchronization logic defers to the server peforming some intelligence in handling duplicate entries for the sync process. The static information that is held on the client for address book sync operations is stored in a file called

which is located in the root directory of the users profile information.

//
// The client keeps a Sync mapping table which holds the following:
//
// ServerRecordID   - Unique ID for a record provided by the
//                    UAB server.
// LocalRecordID    - Local Unique ID, for mobile devices this
//                    is assigned by the mobile device.
// CRC              - CRC of the record last time we synced.
// Flags            - Operation to apply to this record.  ADD
//                    if it's new, MOD if it's been modified,
//                    RET if it was already sent to the server
//                    but an error occured, etc.
//
// Step 1:
// When the user begins a sync, run through the local database and update the
// sync mapping table.  If the CRC has changed, mark the entry modified, if
// it's a new record, add an entry and mark it new, if a record was deleted,
// mark the entry deleted, etc.
//
// Sync approach - server handles all conflict resolution:
//
// Step 2:
// Using the sync mapping table and the local records database, generate the change
// list to send to the server.  Mark any modified or new record with the RET (retry)
// flag.
//
// Step 3:
// Get the response back from the server.  Since the communication was successful,
// clear the RET (retry) flag on all records.  Then apply the server changes back
// to the local database (updating the CRC's in the process).  Save the changes to
// the local database, clear the sync mapping table flags and save the new sync
// mapping table.
//
 
 

#include "nsrootidl.idl"
#include "nsIAbSyncListener.idl"

[scriptable, uuid(91FDFEE1-EFBC-11d3-8F97-000073757374)]
interface nsIAbSyncDriver : nsIAbSyncListener
{
    void KickIt();
};

As you can see, this is a very simple interface which allows for the starting of the address book sync operation. The interface of greater interest is the address book sync listener. This provides feedback of the current sync operation. This interface is as follows:

#include "nsISupports.idl"
#include "nsrootidl.idl"
#include "nsIFileSpec.idl"

[scriptable, uuid(E0ED29E0-098A-11d4-8FD6-00A024A7D144)]
interface nsIAbSyncListener : nsISupports {

    /**
     * Notify the observer that the AB Sync Authorization operation has begun.
     *
     */
    void OnStartAuthOperation();

    /**
     * Notify the observer that the AB Sync operation has been completed.
     *
     * This method is called regardless of whether the the operation was
     * successful.
     *
     *  aTransactionID    - the ID for this particular request
     *  aStatus           - Status code for the sync request
     *  aMsg              - A text string describing the error (if any).
     *  aCookie           - hmmm...cooookies!
     */
    void OnStopAuthOperation(in nsresult aStatus, in wstring aMsg, in string aCookie);

    /**
     * Notify the observer that the AB Sync operation has begun. This method is
     * called only once, at the beginning of a sync transaction
     *
     */
    void OnStartOperation(in PRInt32 aTransactionID, in PRUint32 aMsgSize);

    /**
     * Notify the observer that progress as occurred for the AB Sync operation
     */
    void OnProgress(in PRInt32 aTransactionID, in PRUint32 aProgress, in PRUint32 aProgressMax);

    /**
     * Notify the observer with a status message for sync operation
     */
    void OnStatus(in PRInt32 aTransactionID, in wstring aMsg);

    /**
     * Notify the observer that the AB Sync operation has been completed.
     *
     * This method is called regardless of whether the the operation was
     * successful.
     *
     *  aTransactionID    - the ID for this particular request
     *  aStatus           - Status code for the sync request
     *  aMsg              - A text string describing the error (if any).
     */
    void OnStopOperation(in PRInt32 aTransactionID, in nsresult aStatus,
                         in wstring aMsg);
};