View source for SoC:RoamingSupport

== The Proposal ==
My initial idea is to create a new interface that registers itself as a service with XPCOM. This service will allow objects to register (and unregister if needed) themselves for synchronization push and pull operations. This interface will also provide at least a high-level path for wrapping up the data to sync in a sudo-email message or IMAP implementation. 

The push operations would provide the object a new set of data (in a to-be-determined data structure) and leave the implementation details up to the object.

The pull operation would request data (again in a to-be-determined structure) from the object into the synchronization service.

=== The Sync Service ===
A new service will be introduced into the mailnews component, called <code>nsIMsgRoamingService</code>. This service will delegate notifications between the data classes and roaming update messages. There are two paths of data through the roaming service, as illustrated below:

<div style="text-align: center">[[Image:Flow_dataObjects.png]]</div>
Note: A "data class" is a interface that controls anything that we want synced, like an <code>|nsIMsgFolder|</code>.

The roaming service uses the <code>nsIObserverService</code> to handle passing updates to the data classes. The designated topics for the roaming service can be found in <code>nsMsgRoamingConstants.h</code>. 

The roaming service also maintains the list of update messages that are stored on either the IMAP folder or the POP3 inbox. A typical set of update messages consists of one full update message, followed by a preset number of delta update messages. This setup is illustrated below:

<div style="text-align: center">[[Image:update_messages.png]]</div>

=== Update Messages ===
For containing and controlling the data between installations, update messages are used to package and transport the sync data. All sync information is packed into a file. There are two types of update messages:

* Full Update Message - Contains everything that the user has selected to sync
* Delta Update Message - Contains only the changes since the last full/delta update message.

Some of the sync data can be transferred as the full data file, like the address book's abook.mab file. However, certain data types like user preferences can not be sync'd this way, and contain an update log listed in the file. To help with unpacking all of the data, a TOC file is created and included with each update message. The format of the TOC file looks like this:

  NumItems: 3
  Item0: mbook.ab
  Item1: temp.txt
  Item2: temp2.txt

=== Delivery Options ===
The delivery mechanism should anonymous from the details of the actual storage of the message, wether it be IMAP or POP3. The sync service should be able to pass down something like a file pointer to a temporary sync file. The advantage to storing the updates in an individual file is to keep away from the actual "live" data files, and perhaps create the ability to format the update file in a format of our choosing.

At this stage, we have not determined if the storage options in the delta messages, here are the options I have come up with so far:
* Store all updates for current iteration in one file
* Store each update in an individual delta message
* Store each individual update as individual files in one delta iteration.

The full sync message would contain a renamed zip archive (.zim or whatever) to help preserve with storage space. The message would also be marked not to delete on the server side.

=== Syncing Sessions ===
To help preserve the integrity of the sync, a "sync-log" has been proposed to keep track of all of the changes that have been applied (and probably when they were applied). 

Since shutting down and not syncing would probably suck for the average user, I have planned to add a pref that allows forced synchronization at shutdown. Either the user can build and save our build send the message depending on the pref.

For IMAP-synched sessions, a timer is probably not needed, as changes can be applied as new delta/update messages are posted. The same philosophy can be applied to the POP3 setting, applying sync changes based on the biff-update interval.

== TODO List ==
To help keep things centralized, I'm keeping track of things I need to work on here. Any suggestions made by others will be listed here as well.

* Shutdown &amp; Refresh AB Datasource
* Open IMAP sync folder at startup.
* Mark Update Messages as Read (IMAP not working right?)
* Initial/Temporary UI integration
* Sign Update Messages
* Provide API's to set account preferences
** Sync Account URI
** Pref's to Sync....
* <b>Fix <code>UpdateMessageProcessor</code> leaks</b>

== Service Synchronization Notes ==
* Items to Sync:
** Address Book
** Mail Filters
** Saved Searches
** Newsrc files
** Rss subscriptions
** Tag definitions
** Views
** etc.. (add more)
* When to sync?
** on a set interval (pref?)
** shutdown

== Things to keep in mind: ==
* Make the feature extensible
** A simple interface to inherit?
* Need a way to know that an object has changed
* A way to stream the object to a file, or a file pointer
** for newsrc files, filters, (anything that uses a file)
* Things that aren't stored as a file:
** Account Information
** About everything in account.js
*** Sync tag definitions
** An interface that parses and applies these changes:

----

== Item Synchronization Notes and Ideas ==

Below contains notes for potential hooks for notifying an interface (service possibly) that an object has changed and needs to be synced. These locations might also be ideal for points of entry where the notifying interface could inform the object of changes from an external source.

=== Address Book ===
* Some object that extends from |nsIAbListener|
** |nsAbDirectoryDataSource|
** |nsAbView|

=== Message View Synchronization Ideas ===
|nsMsgMailViewList| seems like the best place from just poking around. I could just set some sinks in that class for when methods like |AddMailView()| and |RemoveMailView()| are called.

=== Mail Filters ===

=== Saved Searches ===

=== News RC ===

=== RSS Feeds ===

=== Saved Preferences ===