Modifying Objects
[API's]

Detailed Description

These functions are provided to track changes to objects as they occur. Any process that needs to create, modify or delete an object in a DataStore outside of a synchronization session should call the begin and end modify functions below.

When an object is successfully modified, the ChangeMgr will send a change notification via the Notification Manager to subscribers registered for the datastore's notifyType, if specified during registration. The notification specifies the type of change and the object affected. A process that plans to make a sequence of modifications can cause a single notification to be sent for the entire sequence by using the ChangeMgr's batch modify API.

The Change Manager does not deal with object content in its "native" form. As a result, it cannot be used to modify objects outside of a synchronization session. Because the Change Manager may need to perform operations both before and after an object's content is changed, it provides begin and end functions that are meant to bracket content changes. The calling application should make the actual change in between calling the begin and end funnctions.

To maximize concurrency, applications should only hold read and write locks for short periods of time. Thus, in general, an application should not hold a read or write lock while waiting for a user to edit a record. Because concurrent edits to a record are possible when the application is not holding a lock, the following scenario is possible:

  1. An application reads the current content for a record into memory and releases its read lock.
  2. The application displays the content for the user to edit.
  3. Meanwhile, another application obtains a write lock, writes the record and releases its write lock.
  4. The user finishes editing the record and commits his/her changes. The changes made by the prior write are lost. To detect and prevent this case, the ChangeMgr provides object and datastore monitors. The monitor remembers which version of an object's content has been read by the calling application. Thus when the application modifies the record, the ChangeMgr can determine whether it is modifying a stale version of the record's content. In this case, the ChangeMgr will either fail the modify or create a conflict, depending on the monitor's policy. No content is lost if a conflict is created.

An application that registered its datastore with dbType kDbTypeSQLite, should perform the following steps to acquire a monitor for a single object:

  1. Start a transaction.
  2. Read and cache the object's content
  3. Call alp_hscm_acquire_object_monitor() and specify the desired policy.
  4. Commit the transaction These steps ensure that no other application can write the object until the content is read and the monitor is acquired.

An application that registered its datastore with dbType kDbTypeSQLite, should perform the following steps to acquire a monitor for the entire datastore:

  1. Start a transaction.
  2. Read and cache the datastore's content (in other words, read and cache all objects in the datastore.
  3. Call alp_hscm_acquire_datastore_monitor() and specify the desired policy.
  4. Commit the transaction


Functions

alp_status_t alp_hscm_acquire_datastore_monitor (AlpHsChangeMgrHandle hChgMgr, AlpHsMonitorPolicyPtr pPolicy, AlpHsMonitorPtr *ppMonitor)
 Acquire a monitor for an entire datastore.
alp_status_t alp_hscm_acquire_object_monitor (AlpHsChangeMgrHandle hChgMgr, AlpLuid objLuid, AlpHsMonitorPolicyPtr pPolicy, AlpHsMonitorPtr *ppMonitor)
 Acquire a monitor for a single object.
alp_status_t alp_hscm_begin_create_with_extended_guid (AlpHsChangeMgrHandle hChgMgr, AlpHsMonitorPtr pMonitor, unsigned int luidCount, AlpLuidPtr pLuids, AlpLuidPtr pNewLuid, AlpHsObjectUpdateHandle *pHandle)
 Create a new object with an extended guid.
alp_status_t alp_hscm_begin_create_with_external_guid (AlpHsChangeMgrHandle hChgMgr, AlpHsMonitorPtr pMonitor, AlpGuidPtr pExternalGuid, AlpLuidPtr pNewLuid, AlpHsObjectUpdateHandle *pHandle)
 Create a new object identified by the input GUID.
alp_status_t alp_hscm_begin_modify (AlpHsChangeMgrHandle hChgMgr, AlpHsObjectState state, AlpHsMonitorPtr pMonitor, AlpLuidPtr pId, AlpLuid localForwardingAddress, AlpHsObjectUpdateHandle *pHandle)
 Begin an object modify.
alp_status_t alp_hscm_begin_modify_batch (AlpHsChangeMgrHandle hChgMgr, AlpHsBatchHandle *phBatch)
 Begin a batch of object modifications.
alp_status_t alp_hscm_end_modify (AlpHsObjectUpdateHandle hChgMgr, bool modifySucceeded, AlpHsMonitorPtr *ppObjectMonitor)
 End an object modify.
alp_status_t alp_hscm_end_modify_batch (AlpHsChangeMgrHandle hChgMgr, bool batchSucceeded)
 End a batch of object modifications.
alp_status_t alp_hscm_get_monitor_policy (AlpHsMonitorPtr pMonitor, AlpHsMonitorPolicyPtr pPolicy)
 Gets the policy associated with a monitor.
alp_status_t alp_hscm_get_monitor_status (AlpHsChangeMgrHandle hChgMgr, AlpHsMonitorPtr pMonitor, AlpHsMonitorStatusPtr pStatus)
 Returns the status associated with a monitor.
alp_status_t alp_hscm_join_modify_batch (AlpHsChangeMgrHandle hChgMgr, AlpHsBatchHandle hBatch)
 Join an batch of object modifications.
alp_status_t alp_hscm_release_monitor (AlpHsChangeMgrHandle hChgMgr, AlpHsMonitorPtr pMonitor)
 Release an object or datastore monitor.
alp_status_t alp_hscm_set_monitor_policy (AlpHsMonitorPtr pMonitor, AlpHsMonitorPolicyPtr pPolicy)
 Sets the policy associated with a monitor.

Function Documentation

alp_status_t alp_hscm_acquire_datastore_monitor (  AlpHsChangeMgrHandle  hChgMgr,
AlpHsMonitorPolicyPtr  pPolicy,
AlpHsMonitorPtr *  ppMonitor
) 
 

Acquire a monitor for an entire datastore.

Parameters:
[in] hChgMgr Handle to an open ChangeMgr
[in] pPolicy The monitor policy
[out] ppMonitor The return value
See also:
alp_hscm_release_monitor().
Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.

alp_status_t alp_hscm_acquire_object_monitor (  AlpHsChangeMgrHandle  hChgMgr,
AlpLuid  objLuid,
AlpHsMonitorPolicyPtr  pPolicy,
AlpHsMonitorPtr *  ppMonitor
) 
 

Acquire a monitor for a single object.

Parameters:
[in] hChgMgr Handle to an open ChangeMgr
[in] objLuid The object's id
[in] pPolicy The monitor policy
[out] ppMonitor The return value
Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.
See also:
alp_hscm_release_monitor().

alp_status_t alp_hscm_begin_create_with_extended_guid (  AlpHsChangeMgrHandle  hChgMgr,
AlpHsMonitorPtr  pMonitor,
unsigned int  luidCount,
AlpLuidPtr  pLuids,
AlpLuidPtr  pNewLuid,
AlpHsObjectUpdateHandle *  pHandle
) 
 

Create a new object with an extended guid.

This is a special version of alp_hscm_begin_modify for new objects. This version creates a special GUID called an extended GUID, which is a combination of 2 or more GUIDs. This extended GUID is the GUID for the new object. Just like alp_hscm_begin_modify for new objects, a new LUID is returned in pNewLuid.

When the object has been created, call alp_hscm_end_modify as normal to tell the Change Manager to accept/reject the new object.

Parameters:
[in] hChgMgr Handle to an open ChangeMgr
[in] pMonitor A pointer to an object or datastore monitor or zero.
[in] luidCount The number of LUIDs in the pLuids array. Array must contain at least 2 luids.
[in] pLuids A pointer to an array of LUIDs to generate the extended GUID with.
[out] pNewLuid The new LUID for this new object.
[out] pHandle The update handle.
Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.
See also:
hs_id_mgr.h.

alp_status_t alp_hscm_begin_create_with_external_guid (  AlpHsChangeMgrHandle  hChgMgr,
AlpHsMonitorPtr  pMonitor,
AlpGuidPtr  pExternalGuid,
AlpLuidPtr  pNewLuid,
AlpHsObjectUpdateHandle *  pHandle
) 
 

Create a new object identified by the input GUID.

This is a special version of alp_hscm_begin_modify for new objects that have already been assigned a GUID. The input pExternalGuid is the GUID for the new object. Just like alp_hscm_begin_modify for new objects, a new LUID is returned in pNewLuid.

When the object has been created, call alp_hscm_end_modify as normal to tell the Change Manager to accept/reject the new object.

Parameters:
[in] hChgMgr Handle to an open ChangeMgr
[in] pMonitor A pointer to an object or datastore monitor or zero.
[in] pExternalGuid Pointer to the object's GUID.
[out] pNewLuid The new luid for this new object.
[out] pHandle The update handle.
Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.

alp_status_t alp_hscm_begin_modify (  AlpHsChangeMgrHandle  hChgMgr,
AlpHsObjectState  state,
AlpHsMonitorPtr  pMonitor,
AlpLuidPtr  pId,
AlpLuid  localForwardingAddress,
AlpHsObjectUpdateHandle *  pHandle
) 
 

Begin an object modify.

When a process is ready to create, modify or delete an object it should perform the following steps:

  1. If this is the first object being written, start a new transaction.
  2. When creating a new object, call this API with state set to kObjectStateNew, pId set to zero and localForwardingAddress set to zero. The API will allocate an new id for the new object and return it in pId.

When modifying an object, call this API with state set to kObjectStateModified, pId set to the object's local id and localForwardingAddress set to zero.

When deleting an object, call this API with state set to kObjectStateDeleted, pId set to the object's local id and localForwardingAddress set to appropriate forwarding address, or zero if there isn't a forwarding address. If specified, the forwarding address must be a referenceable local id.

  1. Create, modify or delete the object.
  2. Call alp_hscm_end_modify().
  3. If this is the last object to be written, then commit or rollback the transaction, depending on the outcome of step 3. Otherwise proceed to the next write by calling alp_hscm_begin_modify().

Parameters:
[in] hChgMgr Handle to an open ChangeMgr
[in] state The intended state
[in] pMonitor A pointer to an object or datastore monitor or zero
[in,out] pId A pointer to the object's id or zero for a new object
[in] localForwardingAddress A pointer to a forwarding address for the object if the intended state is kObjectStateDeleted, or zero
[out] pHandle The update handle
Remarks:
If the calling application passes a monitor for the relevant object or datastore and the object with the input luid *pId was modified by another application after the monitor was acquired, then:
  1. If the monitor's policy is not to create conflicts, the call will fail with the error ALP_STATUS_HOTSINC_OBJ_MODIFIED or ALP_STATUS_HOTSYNC_OBJ_DELETED depending on the object's current state.
  2. If the monitor's policy is to create conflicts, then:
    1. If the input state is kObjectStateDeleted and the input object version is already deleted, the call will fail with error ALP_STATUS_HOTSYNC_OBJ_DELETED, indicating that the delete is unnecessary.
    2. Otherwise the call will succeed with status ALP_STATUS_HOTSYNC_CREATE_CONFLICT. In this case, the application should should do the following:
      1. If the input state state is kObjectStateModified, add a new object with luid equal to the value returned in *pId and flush the old object from the cache. Otherwise, if the input state is kObjectStateDeleted, the ChangeMgr has already marked the object with luid equal to *pId as deleted. Thus the application does not actually have to delete the object from its datastore, but should flush it from its cache.
      2. Call alp_hscm_end_modify() as normal.

When the API needs to create a conflict it may return a new id for the conflicted object version in *pId. Thus the application should always use the value of *pId after the call for any subsequent operations on the object.

Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.

alp_status_t alp_hscm_begin_modify_batch (  AlpHsChangeMgrHandle  hChgMgr,
AlpHsBatchHandle *  phBatch
) 
 

Begin a batch of object modifications.

Although the alp_hscm_begin_modify() and alp_hscm_end_modify() calls may be enclosed in a user defined transaction, the ChangeMgr will still send a single notification for each object modified during the transaction. This causes two distinct problems:

  1. Notifications are sent when alp_hscm_end_modify() is called, not when the transaction is completed. Thus if the transaction later fails, the notifications are erroneous.
  2. Subscribers cannot read the objects modified until the transaction is complete.

To address these problems, the ChangeMgr provides a batch modify mechanism. A call to alp_hscm_begin_modify_batch() starts a transaction that will include any modifications made by subsequent calls to alp_hscm_begin_modify(), alp_hscm_begin_create_with_external_guid(), alp_hscm_begin_create_with_extended_guid() and alp_hscm_end_modify(). A call to alp_hscm_end_modify_batch() ends the transaction by either committing or rolling back all changes since the call to begin the batch. If the batch is committed, the ChangeMgr will send a single notification for the entire batch that specifies the number of objects modified. No notification is sent if the batch fails (since all changes are rolled back).

Parameters:
[in] hChgMgr Handle to an open ChangeMgr
[out] phBatch The new batch.
Returns:
Returns ALP_STATUS_HOTSYNC_OK if successful. Returns ALP_STATUS_HOTSYNC_IN_MODIFY_BATCH when the ChangeMgr is already processing a modify batch. Otherwise returns an error.
Remarks:
The batch handle returned by this function is no longer valid when passed to alp_hscm_end_modify_batch().
See also:
alp_hscm_begin_modify(), alp_hscm_end_modify(), alp_hscm_end_modify_batch(), alp_hscm_join_modify_batch(), alp_hscm_begin_create_with_external_guid(), alp_hscm_begin_create_with_extended_guid().

alp_status_t alp_hscm_end_modify (  AlpHsObjectUpdateHandle  hChgMgr,
bool  modifySucceeded,
AlpHsMonitorPtr *  ppObjectMonitor
) 
 

End an object modify.

When modifySucceeded is true, this call causes the Change Manager to:

  1. Make the changes to its data tables necessary to track the modification.
  2. Send a change notification to registered subscribers, unless the call is within a modify batch.

Parameters:
[in] hChgMgr Handle to an open ChangeMgr
[in] modifySucceeded Indicates whether the modification succeeded
[in,out] ppObjectMonitor Nullable. Pointer to an object monitor
Remarks:
alp_hscm_end_modify() will automatically release *ppObjectMonitor if:
  1. *ppObjectMonitor is not null.
  2. *ppObjectMonitor is an monitor for the object being modified.
  3. A valid object monitor was specified when alp_hs_begin_modify() was called.
  4. A conflict is being created. When these conditions are met and the call succeeds, alp_hscm_end_modify() will also set *ppMonitor to a new object monitor. The new monitor has the same policy as the monitor specified to alp_hscm_begin_modify(). This is useful when an application periodically commits edits to an object while continuing to hold it open for edit.

When this call is made within a modify batch, the modifySucceeded parameter is ignored. Individual modifies within a batch cannot be rolled back.

Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.

alp_status_t alp_hscm_end_modify_batch (  AlpHsChangeMgrHandle  hChgMgr,
bool  batchSucceeded
) 
 

End a batch of object modifications.

Parameters:
[in] hChgMgr Handle to an open ChangeMgr
[in] batchSucceeded Indicates whether the batch succeeded
Remarks:
If batchSucceeded is true, the ChangeMgr will attempt to commit the transaction started by alp_hscm_begin_modify_batch(). If the commit succeeds the ChangeMgr will send a single change notification for each datastore included in the batch. If batchSucceeded is false, the ChangeMgr will attempt to roll back the batch. In this case no notifications are sent.

The batch handle returned by alp_hscm_begin_modify_batch() is no longer valid when this call is made.

Returns:
Returns ALP_STATUS_HOTSYNC_OK if successful. Returns ALP_STATUS_HOTSYNC_NOT_IN_MODIFY_BATCH if the ChangeMgr is not in a modify batch. Otherwise returns an error.
See also:
alp_hscm_begin_modify_batch().

alp_status_t alp_hscm_get_monitor_policy (  AlpHsMonitorPtr  pMonitor,
AlpHsMonitorPolicyPtr  pPolicy
) 
 

Gets the policy associated with a monitor.

Parameters:
[in] pMonitor Pointer to a monitor
[in,out] pPolicy The monitor's current policy
Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.
See also:
alp_hscm_get_monitor_policy().

alp_status_t alp_hscm_get_monitor_status (  AlpHsChangeMgrHandle  hChgMgr,
AlpHsMonitorPtr  pMonitor,
AlpHsMonitorStatusPtr  pStatus
) 
 

Returns the status associated with a monitor.

When passed an object monitor, this function will set pStatus->modifiedCount to 1 if the object has been modified since the monitor was acquired; it will set pStatus->deletedCount to 1 if the object has been deleted since the monitor was acquired. If either count is non-zero, an attempt to write the object will cause a conflict or an error, depending on the monitor's policy.

When passed a datastore monitor, this function will set pStatus->modifiedCount and pStatus->deletedCount to the number of objects modified and deleted in the datastore since the monitor was acquired.

Parameters:
[in] hChgMgr Handle to an open ChangeMgr
[in] pMonitor Pointer to a monitor
[in,out] pStatus The monitor's current status
Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.

alp_status_t alp_hscm_join_modify_batch (  AlpHsChangeMgrHandle  hChgMgr,
AlpHsBatchHandle  hBatch
) 
 

Join an batch of object modifications.

When datastores share storage, it can be useful to include all of them in a single batch. For example, when importing contacts from a SIM card the contacts application must create objects in three datastores that share the same sqlite database. Creating a batch that includes just one datastore prevents dependent changes from being made in the other contacts datastores. To address this problem, the ChangeMgr allows a datastore to join an existing batch, provided it shares the same database handle and registered for the same notify type. Any changes made to the datastore once it joins the batch become a part of the transaction started by alp_hscm_begin_modify_batch() and are either committed or rolled back when alp_hscm_end_modify_batch() is called.

Parameters:
[in] hChgMgr Handle to an open ChangeMgr
[in] hBatch The batch to join.
Returns:
Returns ALP_STATUS_HOTSYNC_OK if successful. Returns ALP_STATUS_HOTSYNC_IN_MODIFY_BATCH if the ChangeMgr is already in a modify batch. Returns ALP_STATUS_HOTSYNC_INCOMPATIBLE_MODIFY_BATCH if the input ChangeMgr is open for a datastore that uses a different database handle or registered with a different notifyType. Otherwise returns an error.
See also:
alp_hscm_begin_modify_batch().

alp_status_t alp_hscm_release_monitor (  AlpHsChangeMgrHandle  hChgMgr,
AlpHsMonitorPtr  pMonitor
) 
 

Release an object or datastore monitor.

This function deallocates all resource associated with the input monitor.

Parameters:
[in] hChgMgr Handle to an open ChangeMgr
[in] pMonitor Pointer to a monitor
Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.

alp_status_t alp_hscm_set_monitor_policy (  AlpHsMonitorPtr  pMonitor,
AlpHsMonitorPolicyPtr  pPolicy
) 
 

Sets the policy associated with a monitor.

Parameters:
[in,out] pMonitor Pointer to a monitor
[in] pPolicy The monitor's new policy
Returns:
If successful returns ALP_STATUS_HOTSYNC_OK; otherwise returns an error.
See also:
alp_hscm_get_monitor_policy().

Generated on Wed Jul 30 07:06:41 2008 by Doxygen 1.4.6 for ALP SDK + Hiker Documentation

Copyright © 1999-2008 ACCESS CO., LTD. All rights reserved.