You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.



Address Book Sync Client Design
by Richard H. Pizzarro <rhp@netscape.com>

Contents

Overview
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:
 
Mozilla UI
 
AB Sync Logic
Mork AB Database
Sync Protocol Encoding
Sync Protocol Decoding
HTTP "POST" API
Mozilla Networking

 
Client Side Sync Logic
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 absync.dat 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.
//
 
 
Public Interfaces
There is a very simple interface to the address book sync component. This interface is defined in  mozilla/mailnews/addrbook/public/nsIAbSyncDriver.idl

#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);
};


Last modified: Mon Nov 13, 2000 rhp@netscape.com