Server Synchronization
[API's]

Detailed Description

These functions are used to synchronize with a standard SyncML Server.

To use the write modified object API with a ChangeMgr that is opened for server sync, set the state, local and external fields of AlpHsObject instead of the global fields. In particular set the localId to the correct local id or zero, set the external id to zero or the server's object id, set state to the correct state and set localForwardingAddress to the new forwarding address or zero. If the server resolved a conflict for the specified object by merging content, then set isDominant to true, otherwise set it to false. The other fields do not need to be initialized. The ChangeMgr will assign a new id if necessary and use the stored server information to compute the object's pedigree. When the object's state is kObjectStateNew, the ChangeMgr will add an entry to its map table that contains the specified external id and the object's new local id. alp_hscm_write_next_modified_object() will fill in the remote fields of the input object, namely the globalId, globalForwardingAddress and (global) priority.

Functions

alp_status_t alp_hscm_get_last_anchors (AlpHsChangeMgrHandle hChgMgr, AlpHsAnchorPtr pLocalAnchor, AlpHsServerAnchor serverAnchor, AlpHsPedigreePtr *ppCoverage)

Retrieves the coverage, last local anchor and last server anchor values for an open datastore.

alp_status_t alp_hscm_get_next_anchor (AlpHsChangeMgrHandle hChgMgr, AlpHsAnchorPtr pNextAnchor)

Retrieves the local next anchor value for the current server.

alp_status_t alp_hscm_get_next_id_mapping (AlpHsIdMapIteratorPtr pIter, AlpHsServerId externalId, AlpLuidPtr pLuid)

Gets the next id mapping from an id map iterator.

alp_status_t alp_hscm_is_refresh_required (AlpHsChangeMgrHandle hChgMgr, bool *pIsRequired)

alp_status_t alp_hscm_open_for_server_sync (const _TCHAR *syncMgrLocURI, const _TCHAR *nodeId, const _TCHAR *serverId, uint32_t userId, void *pContext, AlpHsObjectComparatorFnPtr cmpObjs, AlpHsChangeMgrHandle *phChgMgr)

Open the ChangeMgr for synchronization with a standard SyncML server.

alp_status_t alp_hscm_query_server_id_map (AlpHsChangeMgrHandle hChgMgr, const _TCHAR *locURI, AlpHsIdMapIteratorPtr *ppIter)

Retrieve an iterator over the current server's id map for the specified datastore.

alp_status_t alp_hscm_register_server (AlpHsServerRegistrationPtr pReg)

Register a new server.

alp_status_t alp_hscm_reset_last_anchors (AlpHsChangeMgrHandle hChgMgr)

Resets the last anchor values for the current server and datastore.

alp_status_t alp_hscm_set_last_anchors (AlpHsSnapshotHandle hSnapshot, bool delMapEntries)

Updates coverage and anchor values for an open datastore and server.

alp_status_t alp_hscm_set_next_server_anchor (AlpHsSnapshotHandle hSnapshot, const _TCHAR *locURI, AlpHsSyncType syncType, AlpHsServerAnchor nextServerAnchor)

Records the server's next anchor value for the specified datastore in the input snapshot.

Function Documentation

alp_status_t alp_hscm_get_last_anchors ( AlpHsChangeMgrHandle hChgMgr,

AlpHsAnchorPtr pLocalAnchor,

AlpHsServerAnchor serverAnchor,

AlpHsPedigreePtr * ppCoverage

)

Retrieves the coverage, last local anchor and last server anchor values for an open datastore.
This API retrieves the coverage, last local anchor and last server anchor values for the current server and datastore. It is used to retrieve the last anchor values for each datastore to be included in the sync. The coverage returned should be used as the bottom cover when the current datastore is added to the sync snapshot.

Parameters:

[in] hChgMgr Handle to a ChangeMgr open for a datastore

[out] pLocalAnchor The last local anchor value sent to the server for the current open datastore

[out] serverAnchor The last anchor sent from the server for the current open datastore

[out] ppCoverage The server's coverage for this datastore

Remarks:
If the datastore has not previously been synced with the current server, the output anchor values will be zero and the output coverage will be NULL.
The input ChangeMgr handle must have been opened by calling alp_hscm_open_for_server_sync() then used to open a particular datastore by calling alp_hscm_open_datastore().
The server's coverage for each datastore records the changes that have been sent to the server from the datastore.

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

See also:
alp_hscm_open_for_server_sync(), alp_hscm_get_next_anchor().

alp_status_t alp_hscm_get_next_anchor ( AlpHsChangeMgrHandle hChgMgr,

AlpHsAnchorPtr pNextAnchor

)

Retrieves the local next anchor value for the current server.
This API returns the next value of the current server's local clock. This is the the next anchor value for each local datastore to be included in the next sync with the current server.

Parameters:

[in] hChgMgr Handle to a ChangeMgr open for server sync

[out] pNextAnchor The return value

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

See also:
alp_hscm_open_for_server_sync().

alp_status_t alp_hscm_get_next_id_mapping ( AlpHsIdMapIteratorPtr pIter,

AlpHsServerId externalId,

AlpLuidPtr pLuid

)

Gets the next id mapping from an id map iterator.

Parameters:

[in] hChgMgr Handle to a ChangeMgr open for server sync

[in,out] externalId The server's object id

[out] pLuid The local id for the same object

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

See also:
alp_hscm_query_server_id_map().

alp_status_t alp_hscm_is_refresh_required ( AlpHsChangeMgrHandle hChgMgr,

bool * pIsRequired

)

Parameters:

[in] hChgMgr Handle to an open ChangeMgr

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

alp_status_t alp_hscm_open_for_server_sync ( const _TCHAR * syncMgrLocURI,

const _TCHAR * nodeId,

const _TCHAR * serverId,

uint32_t userId,

void * pContext,

AlpHsObjectComparatorFnPtr cmpObjs,

AlpHsChangeMgrHandle * phChgMgr

)

Open the ChangeMgr for synchronization with a standard SyncML server.
This API opens the ChangeMgr for syncing to a previously registered SyncML server.

Parameters:

[in] syncMgrLocURI The caller's locURI

[in] nodeId Desktop only. On ALP, this parameter must be set to ALP_HS_DEFAULT_NODE_NAME.

[in] serverId The server's id.

[in] userId Desktop only.

[in] pContext Desktop only.

[in] cmpObjs Desktop only.

[out] phChgMgr Pointer to a ChangeMgr handle.

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

See also:
alp_hscm_register_server().

alp_status_t alp_hscm_query_server_id_map ( AlpHsChangeMgrHandle hChgMgr,

const _TCHAR * locURI,

AlpHsIdMapIteratorPtr * ppIter

)

Retrieve an iterator over the current server's id map for the specified datastore.

Parameters:

[in] hChgMgr Handle to a ChangeMgr open for server sync

[in] locURI The datastore's locURI

[out] ppIter Pointer to an Id Map iterator poinger

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

See also:
alp_hscm_get_next_id_mapping().

alp_status_t alp_hscm_register_server ( AlpHsServerRegistrationPtr pReg )

Register a new server.
This API registers the input server with the ChangeMgr and creates a new clock for the server.

Parameters:

[in] pReg The server's registration information.

Remarks:
This API does not depend on how the ChangeMgr was opened.

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

See also:
alp_hscm_open_for_server_sync().

alp_status_t alp_hscm_reset_last_anchors ( AlpHsChangeMgrHandle hChgMgr )

Resets the last anchor values for the current server and datastore.
This API clears the anchors and coverage pedigrees for the current open datastore and server. It is typically called when a slow sync is necessary with the current server.

Parameters:

[in] hChgMgr Handle to a ChangeMgr open for server sync

Remarks:
The input ChangeMgr handle must have been opened by calling alp_hscm_open_for_server_sync() then used to open a particular datastore by calling alp_hscm_open_datastore().

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

See also:
alp_hscm_set_last_anchors().

alp_status_t alp_hscm_set_last_anchors ( AlpHsSnapshotHandle hSnapshot,

bool delMapEntries

)

Updates coverage and anchor values for an open datastore and server.
This function is normally called after a successful server sync. It is used to update the coverage and anchor information used for fast synchronization with the current server. It performs the following tasks atomically:

For each datastore in the snapshot that has a nextServerAnchor:

Sets the last local anchor to the next value of the server's clock (this is the same value returned by alp_hscm_get_next_anchor()).
Sets the server's datastore coverage to the snapshot top cover plus the server's current clock value. Note that this step is NOT performed when the datastore's sync type is client or server alerted one way or refresh sync from server, since these sync types do not include changes from the client.
Sets the last server anchor to the nextServerAnchor.
Deletes the server's id map entries (if delMapEntries is true).

Increments the server's clock.

Parameters:

[in] hSnapshot Handle to an open snapshot

[in] delMapEntries Boolean that specifies whether to delete id mappings for new object's from the current server

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

See also:
alp_hscm_set_next_server_anchor(), alp_hscm_get_last_anchors(), alp_hscm_get_next_anchor().

alp_status_t alp_hscm_set_next_server_anchor ( AlpHsSnapshotHandle hSnapshot,

const _TCHAR * locURI,

AlpHsSyncType syncType,

AlpHsServerAnchor nextServerAnchor

)

Records the server's next anchor value for the specified datastore in the input snapshot.

Parameters:

[in] hSnapshot Handle to an open snapshot

[in] locURI The datastore's locURI

[in] nextServerAnchor The server's next anchor value for the specified datastore

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

See also:
alp_hscm_set_last_anchors().

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


Functions
alp_status_t	alp_hscm_get_last_anchors (AlpHsChangeMgrHandle hChgMgr, AlpHsAnchorPtr pLocalAnchor, AlpHsServerAnchor serverAnchor, AlpHsPedigreePtr *ppCoverage)
	Retrieves the coverage, last local anchor and last server anchor values for an open datastore.
alp_status_t	alp_hscm_get_next_anchor (AlpHsChangeMgrHandle hChgMgr, AlpHsAnchorPtr pNextAnchor)
	Retrieves the local next anchor value for the current server.
alp_status_t	alp_hscm_get_next_id_mapping (AlpHsIdMapIteratorPtr pIter, AlpHsServerId externalId, AlpLuidPtr pLuid)
	Gets the next id mapping from an id map iterator.
alp_status_t	alp_hscm_is_refresh_required (AlpHsChangeMgrHandle hChgMgr, bool *pIsRequired)
alp_status_t	alp_hscm_open_for_server_sync (const _TCHAR syncMgrLocURI, const _TCHAR nodeId, const _TCHAR serverId, uint32_t userId, void pContext, AlpHsObjectComparatorFnPtr cmpObjs, AlpHsChangeMgrHandle *phChgMgr)
	Open the ChangeMgr for synchronization with a standard SyncML server.
alp_status_t	alp_hscm_query_server_id_map (AlpHsChangeMgrHandle hChgMgr, const _TCHAR locURI, AlpHsIdMapIteratorPtr ppIter)
	Retrieve an iterator over the current server's id map for the specified datastore.
alp_status_t	alp_hscm_register_server (AlpHsServerRegistrationPtr pReg)
	Register a new server.
alp_status_t	alp_hscm_reset_last_anchors (AlpHsChangeMgrHandle hChgMgr)
	Resets the last anchor values for the current server and datastore.
alp_status_t	alp_hscm_set_last_anchors (AlpHsSnapshotHandle hSnapshot, bool delMapEntries)
	Updates coverage and anchor values for an open datastore and server.
alp_status_t	alp_hscm_set_next_server_anchor (AlpHsSnapshotHandle hSnapshot, const _TCHAR *locURI, AlpHsSyncType syncType, AlpHsServerAnchor nextServerAnchor)
	Records the server's next anchor value for the specified datastore in the input snapshot.

Server Synchronization [API's]

Detailed Description

Functions

Function Documentation

Server Synchronization
[API's]