This is the documentation for the OSync project. First it gives a short overview for users, then some technical explanations.
User documentation
OSync User Interface
The OSync
GUI is very
basic. It consists of the screen that you can see in the
screenshot on the right.
There are three different settings.
- Your name:
- This name is used for tagging your outgoing calendar events. This is required so that other people can easily distinguish between their own items and the ones you shared with them.
- Send to:
- This is the address where the synchronization messages are sent to. If you only share with one person this can be the other user's address. Otherwise it is recommended to set up a mailing list with all recipients in the list.
- Share category:
- All calendar items with this category are shared. Attention: You should not change this after you have started sharing calendar events.
Working in Outlook
You can continue to create Outlook appointments like you
always did. There are only two events in which OSync becomes
active:
- Incoming OSync mail
- When a mail sent out by the OSync program arrives in your
Inbox, it is processed. This means that new calendar items are
created or existing ones edited or deleted. After this, this
mail message is deleted.
It is very important that you do not move this OSync synchronization messages. OSync only looks for them in the Inbox, but not in any other folders. - Calendar item with the synchronization category
- When you create, edit or delete a calendar item with a specified category, OSync will automatically send the synchronization message to subscribers.
Calendar items by other users are prepended with their name enclosed in square brackets. So you can quickly distinguish between your calendar items and the ones from other people.
Technical documentation
OSync is a Python program. Outlook is controlled using OLE. I will explore two important points of the project:
- Format of the synchronization messages
- Basic algorithm of synchronization
Synchronization messages
The synchronization is done using pickle. Pickle is an object serialization method offered by Python. So basically I construct an event list in memory using class objects. Then I pickle this list and insert it into the outgoing mail message. On the receiving side, the pickle text is extracted from the mail message and then unpickled.
The class which is pickled is called SyncData and consists of two lists called events and deleted. The former is a list of Event objects with all created or modified events. The latter is a list of all deleted event's EntryIDs.
The E-mail body contains a short message which explains the content of the mail message to the user. It is then followed by the following text:
SYNC STARTS HERE (v1):
======================
CONTENT
====================
SYNC ENDS HERE
CONTENT is the place where the pickled data is inserted. The text v1 in the brackets indicates the version number of the mail format. This can be changed in the future to v2 or higher in order to create a new mail format. This new messages will then be ignored by older OSync versions.