An external datastore is a datastore that uses its own ID and change system to track what records and objects have been added/modified/deleted. During a sync, the Hotsync Change Manager works on AlpLuids, which is incompatible with an external datastore's external IDs.
To allow external datastores to participate in a sync, the Change Manager reads external IDs that have been added/modified/deleted from the external datastore using the API alp_hsds_ext_get_change_info. The Change Manager then generates a corresponding AlpLuid for each external ID. These AlpLuids are then used as part of the sync process. The Change Manager maintains a mapping of these AlpLuids to external IDs so that it has a way of referring to the same external IDs during the sync and in subsequent syncs.
The Change Manager also records the modification status of each external ID received from alp_hsds_ext_get_change_info. Once all of the modifications have been recorded, the Change Manager calls alp_hsds_ext_clear_change_info, which signals the external datastore that all changes have been recorded.
These two calls occur at the beginning of sync, when the Sync Manager calls alp_hscm_prepare_for_sync, which gives the Change Manager a chance to perform extra preparation steps before the sync starts.
EXAMPLE: Consider a sample memo app called ExampleMemoApp. The ExampleMemoApp uses strings to identify each record, and integers to identify the change status. The memo ID strings are generated from an alphabet scheme. For example, the first memo would have an ID of "A", the second "B", and so on. The change status is a simple integer, so 0 means no modification, 1 added, 2 modified, 3 deleted. When the user adds a new memo to ExampleMemoApp, that new memo has an ID of "A" and a status of 1 (added).
At the beginning of a sync, the Sync Manager calls alp_hscm_prepare_for_sync, so that the Change Manager can a perform extra preparation steps before the sync starts. In this call, the Change Manager calls alp_hsds_ext_get_change_info, and the external datastore reports the ID "A", with a status of kObjectStateNew for its newly added memo.
The Change Manager generates an AlpLuid for "A", for example, 1000, and stores this mapping of "A" <-> 1000 internally. The AlpLuid of 1000 is used to represent the "A" memo for the rest of sync. The Change Manager then records that the AlpLuid of 1000 was a newly added object.
Since this is the only change reported by the external datastore, the Change Manager next calls alp_hsds_ext_clear_change_info. The external datastore then changes the status of the "A" memo to 0, because the added memo was properly recorded, and does not need to be reported to the Change Manager again until the user makes a modification.
This completes the alp_hscm_prepare_for_sync call made by the Sync Manager. The Sync Manager then proceeds with the sync procedure.
In a subsequent sync, if the Sync Manager detects that another app has modified the memo at AlpLuid 1000, the Sync Manager calls the Change Manager with the new memo and an AlpLuid of 1000. The Change Manager looks up 1000 in its internal table and finds "A" as the corresponding external ID. The Change Manager makes the call to alp_hsds_ext_replace, passing "A" as the external ID. The ExampleMemoApp can use "A" to find the exact memo to be modified and replace its current memo with the new memo. END EXAMPLE
Most of the external datastore's APIs are similar to the datastore APIs in hs_data_store.h. The main difference is that the external datastores are called with external IDs, instead of AlpLuids. Also, several addition APIs have been added to allow the external datastore to work with the Change Manager:
For grouping external datastore actions together into a transaction: alp_hsds_ext_begin_db_transaction, alp_hsds_ext_end_db_transaction, alp_hsds_ext_rollback_db_transaction
For allowing the Change Manager to read newly added/modified/deleted IDs from the external datastore: alp_hsds_ext_get_change_info, alp_hsds_ext_clear_change_info
Data Structures | |
| struct | AlpHsExtChangesReportSet |
| Contains an array of added/modified/deleted external IDs. More... | |
Functions | |
| alp_status_t | alp_hsds_ext_add (AlpHsDataStoreHandle hDs, AlpHsObjectTypePtr pSrcType, bool isReferenceable, AlpHsExternalID *pComponentExtIds, size_t componentExtIdSize, size_t offset, bool moreData, size_t bufSize, const _TCHAR *pBuf, AlpHsExternalID *pNewExtId) |
| Add an object. | |
| alp_status_t | alp_hsds_ext_begin_db_transaction (AlpHsDataStoreHandle hDs) |
| Start a transaction on the datastore's content. | |
| alp_status_t | alp_hsds_ext_clear_change_info (AlpHsDataStoreHandle hDs) |
| Clears the status tracking flags after successfully recording all IDs from alp_hsds_ext_get_change_info. | |
| alp_status_t | alp_hsds_ext_close (AlpHsDataStoreHandle hDs) |
| Closes an external datastore. | |
| alp_status_t | alp_hsds_ext_delete (AlpHsDataStoreHandle hDs, AlpHsExternalID *pExtId) |
| Delete an object. | |
| alp_status_t | alp_hsds_ext_end_db_transaction (AlpHsDataStoreHandle hDs) |
| Commit a transaction that was started in alp_hsds_ext_begin_db_transaction. | |
| alp_status_t | alp_hsds_ext_get_change_info (AlpHsDataStoreHandle hDs, AlpHsExtChangesReportSet *report_set, int16_t iCountRead, bool *moreData) |
| Gets an array of added/modified/deleted records from an external datastore since the last sync. | |
| alp_status_t | alp_hsds_ext_is_version_current (AlpHsDataStoreHandle hDs, AlpHsDataStoreVersionType type, uint32_t version, bool *isCurrent) |
| Determine whether the capabilities or string table version is current. | |
| alp_status_t | alp_hsds_ext_open (const _TCHAR *locURI, uint32_t userId, AlpHsDataStoreHandle *phDs) |
| Opens an external datastore. | |
| alp_status_t | alp_hsds_ext_read (AlpHsDataStoreHandle hDs, AlpHsObjectTypePtr pTgtType, AlpHsExternalID *pExtId, size_t offset, bool *moreData, size_t *pBufSize, _TCHAR *pBuf) |
| Read an object's content. | |
| alp_status_t | alp_hsds_ext_read_capabilities (AlpHsDataStoreHandle hDs, uint32_t *pCurrentVersion, size_t *pSize, _TCHAR *pBuffer) |
| Read the DataStore's capabilities. | |
| alp_status_t | alp_hsds_ext_read_string_table (AlpHsDataStoreHandle hDs, AlpHsObjectTypePtr pObjType, uint32_t *pCurrentVersion, size_t *pSize, _TCHAR *pBuffer) |
| Read the DataStore's WBXML string table for the input object type. | |
| alp_status_t | alp_hsds_ext_replace (AlpHsDataStoreHandle hDs, AlpHsObjectTypePtr pSrcType, AlpHsExternalID *pExtId, size_t offset, bool moreData, size_t bufSize, const _TCHAR *pBuf, bool *pExtIdChanged) |
| Replace an object's content. | |
| alp_status_t | alp_hsds_ext_rollback_db_transaction (AlpHsDataStoreHandle hDs) |
| Roll back a transaction that was started in alp_hsds_ext_begin_db_transaction. | |
| alp_status_t | alp_hsds_ext_update (AlpHsDataStoreHandle hDs, AlpHsObjectTypePtr pSrcType, AlpHsExternalID *pExtId, size_t offset, bool moreData, size_t bufSize, const _TCHAR *pBuf, bool *pExtIdChanged) |
| Update an object's content. | |
|
||||||||||||||||||||||||||||||||||||||||||||
|
Add an object. The HotSync Change Manager calls this function repeatedly to iteratively add a new object to a DataStore. Each call specifies the next bufSize bytes of the new object's content formatted according to the specified srcType. For an external datastore, this function must fill out the external ID with a new ID for this object and also specify the byte length of the external ID.
|
|
|
Start a transaction on the datastore's content. The Hotsync Change Manager will call this function before it writes content to this datastore. The datastore is expected to start a transaction on its content. If the Change Manager successfully writes content to this datastore, the Change Manager will call alp_hsds_ext_end_db_transaction so the datastore can commit the newly added content. If the Change Manager encounters an error, the Change Manager will call alp_hsds_ext_rollback_db_transaction, and the datastore is expected to restore its content back to the state it was in when alp_hsds_ext_begin_db_transaction was called.
|
|
|
Clears the status tracking flags after successfully recording all IDs from alp_hsds_ext_get_change_info. After the Hotsync Change Manager has received and successfully recorded all added/modified/deleted record IDs since the last sync, the Change Manager will call this function to let the external datastore know of its success. The external datastore is expected to clear its status tracking flags on these records and perform other cleanup functions. For example, a record that was marked as deleted can finally be deleted here.
|
|
|
Closes an external datastore. The datastore can free memory that may have been allocated for this datastore handle.
|
|
||||||||||||
|
Delete an object. The HotSync Change Manager calls this function to delete an object from a DataStore.
|
|
|
Commit a transaction that was started in alp_hsds_ext_begin_db_transaction. The datastore is expected to save the new data that was added since alp_hsds_ext_begin_db_transaction was called.
|
|
||||||||||||||||||||
|
Gets an array of added/modified/deleted records from an external datastore since the last sync. At the beginning of sync, the Hotsync Change Manager will ask for all of the added/modified/deleted records IDs since the last sync. The Change Manager will record these IDs into its change management system, and then proceed with the sync operation. The Change Manager will allocate one AlpHsExtChangesReportSet object, and then allocate an array of AlpHsExternalObject within the report set object. The report set object's 'buffcount' variable indicates the size of this array, and the 'size' variable is initially set to 0. The external datastore is expected to fill in the array with record IDs of all added/modified/deleted records since the last sync. The external datastore must also fill the report set object's 'size' variable of the actual number of records that was filled into the array. If there are no changed records, the external datastore would fill the 'size' variable with a 0. For example, the Change Manager may create an array capable of receiving 500 record IDs. The external datastore has 10 changed record IDs. The external datastore would fill in the first 10 elements of the array, and set the 'size' variable to 10. If the external datastore has more changed records than the array can hold, the external datastore must set moreData to 'true', so that the Change Manager can make subsequent call(s) to receive the rest of the changes. When all of the changes have been filled, moreData must be set to 'false' to tell the Change Manager that all changes have been filled into the array. 'iCountRead' is used to indicate how many record IDs the Change Manager has processed so far.
Example: When the Change Manager successfully records all changes, alp_hsds_ext_clear_change_info is called so the external datastore can clear its status tracking flags.
|
|
||||||||||||||||||||
|
Determine whether the capabilities or string table version is current.
|
|
||||||||||||||||
|
Opens an external datastore. The external datastore must generate a unique handle and return it in phDs. This handle is used in subsequent datstore calls. When the datastore is no longer needed, alp_hsds_ext_close is called to close the datastore. When the datastore is opened for sync, there may be special cases where the datastore is not able to participate in the current sync session, and wants to be ignored for the rest of the current sync session without aborting the sync session itself. In this case, the datastore can return ALP_STATUS_DATASTORE_IGNORE_DATASTORE or ALP_STATUS_DATASTORE_IGNORE_AGENT to tell the sync session to ignore this datastore only, or all datastores of this agent, respectively, for the rest of sync.
|
|
||||||||||||||||||||||||||||||||
|
Read an object's content. The HotSync Change Manager calls this function repeatedly to iteratively read an object's content from a DataStore. Each call should return the next *pBufSize bytes of the object's content formatted according to the specified tgtType. When a read attempt fails due to an active or pending writer, this function should return ALP_HOTSYNC_DATASTORE_BUSY. This will cause the Change Manager to retry the read.
|
|
||||||||||||||||||||
|
Read the DataStore's capabilities.
|
|
||||||||||||||||||||||||
|
Read the DataStore's WBXML string table for the input object type.
|
|
||||||||||||||||||||||||||||||||||||
|
Replace an object's content. The HotSync Change Manager calls this function repeatedly to iteratively replace the content for an object that is already present in the DataStore. Each call specifies the next bufSize bytes of the object's new content formatted according to the specified srcType.
|
|
|
Roll back a transaction that was started in alp_hsds_ext_begin_db_transaction. The datastore is expected to restore its content back to the state it was in when alp_hsds_ext_begin_db_transaction was called.
|
|
||||||||||||||||||||||||||||||||||||
|
Update an object's content. The HotSync Change Manager calls this function repeatedly to iteratively update the content for an object that is already present in the DataStore. Each call specifies the next bufSize bytes of the object's changed content formatted according to the specified srcType. Unlike a replace, an update does not replace the entire object's content; instead only the specific fields present in the input content are replaced; the value for other fields remains unchanged.
|
Generated on Wed Jul 30 07:06:42 2008 by Doxygen 1.4.6 for ALP SDK + Hiker Documentation
Copyright © 1999-2008 ACCESS CO., LTD. All rights reserved.