ACCESS Linux Platform applications need to be sync-aware from ground up. ACCESS Linux Platform PIM applications need to participate in SyncML based sync solution that ACCESS Linux Platform HotSync supports. Applications are free to store their data as they wish - in sqlite databases, in the file system or a combination of the two.
To participate in sync, an application needs to present logical objects (it can construct this from the physical data stored in the various locations). Each object must have a unique identifier (LUID). In addition, the application is responsible for informing the Change Manager when the logical object is modified (created / updated / deleted).
All of these facilities are available as part of Sync Services. For the most part, applications will interact with the Change Manager.
Making an Application "Sync-Aware"
The following are the main tasks to make an application sync-aware. Note that you will need to do this on the device as well as on the desktop (i.e. you will need a corresponding implementation on the desktop to sync your data with).
1.LUIDs
ACCESS Linux Platform applications should use Locally Unique Ids (LUID: unique across the device) to uniquely identify a logical object/ record in their database. The ID Manager generates LUIDs (and maps them to GUIDs). However, applications get the ID by calling the Change Manager function: alp_hscm_begin_modify() with pId set to zero. The function will then allocate an ID for the new object and return it in pId.
NOTE: If certain applications have multiple tables to hold info about a logical object, they are free to use auto-generated sqlite IDs for individual rows. However, they must use LUIDs returned by the Change Manager for the composite / logical object that needs to be synchronized. Also, note that LUIDs can be used to reference records on the device. These references will be synchronized correctly to the desktop (as long as the referential relationship is expressed appropriately by the Data Store implementation).
2. Model categories as sync-able items
ACCESS Linux Platform supports objects being in multiple categories; i.e. an object can belong to multiple categories and a category can have multiple objects within it (many-many, M x N relationship). To ensure accuracy of syncing changes to categories/ memberships, applications must model categories as first-class, sync-able data items. What this means in practical terms is that you will need to store content, category-definition and category membership in different tables. Each entry in the category-membership table will contain the ID of content object and the ID of the category object. Changes to each object in the Content, Category & Membership data store will be tracked separately; there will be separate Data Stores for each (more on this later!).
3. Track Changes
Applications need to track changes to their data. This means applications need to inform the Change Manager (part of Sync Services) anytime a change occurs to the object / database. Following operations are treated as changes to the database
- Insert a new object/ data item: Applications need to request for a new Locally unique ID from Change Manager and use it to uniquely identify the newly inserted row. After a successful insert operation, application needs to inform Change Manager by calling the
alp_hscm_end_modify()function - Modify an existing object/ data item: Call
alp_hscm_begin_modify(), passing in the ID of the object being modified. After a successful Edit operation, the application needs to inform Change Manager by callingalp_hscm_end_modify(). - Delete an existing object/ data item: the application must call the
alp_hscm_delete()function in the Change Manager. The Change Manager will then call the Data Store implementation to actually delete the object from storage. See the documentation for further info on forwarding addresses when you delete a reference-able object!
Its preferable that applications make the Change Manager calls as part of the originating operation.(i.e make the actual Insert/modify/delete operation and the Change Manager calls as part of one transaction). See the Sync Services API documentation for further details.
4. Register with Change Manager/ HotSync
All applications that participate in sync need to register it's Data Store (see next item) with Change Manager (specifying their URI, the supported MIME types, etc.) This is achieved by calling the alp_hscm_register_data_store() function. This registration needs to happen once after a hard-reset. The application can do this as part of "lazy" application initialization while creating it's databases, etc. (i.e. at application start-up, check if we've already registered / created DB, etc. If not, do it now).
5. Implement Data Store
Each application must implement & register a Data Store. This Data Store is responsible for presenting the logical object in MIME / sync-able format. When a sync session begins for a particular Data Store, the Data Store implementation will be called to participate in the sync. At the beginning, sync will request changes made to the database. Once it gets back changes from the server, the Change Manager (at the end of sync) will send those updates to the Data Store. The Data Store must then translate the objects from MIME format to internal storage format and store it in the application's database. For more details on this see the HotSync Data Store APIs. As described earlier, if an application uses categories, it must implement separate Data Stores for Content, Category and Membership
