Reading and Writing Objects
[API's]

Detailed Description

The HotSync Change Manager calls these functions to read, write, delete, copy and rekey content objects in a logical DataStore. Reads and Writes are both iterative; that is, multiple API calls may be required to read or write a single object. This minimizes the space required for double buffering the object's content.

Content is read and written in MIME format. The DataStore indicates the MIME types it supports in its capabilities. The Change Manager always reads and writes content that is formatted in one the DataStore's supported types, although reads and writes may use different types.

If the DataStore registered support for SQLite, the Change Manager starts a transaction and obtains an EXCLUSIVE lock before writing objects. The Change Manager ends the transaction after ALL objects have been written. This avoids the additional journal overhead incurred when objects are written in separate transactions.

Functions

alp_status_t alp_hsds_add (AlpHsDataStoreHandle hDs, AlpHsObjectTypePtr pSrcType, bool isReferenceable, AlpLuid newId, AlpLuid *pComponentIds, size_t componentIdSize, size_t offset, bool moreData, size_t bufSize, const _TCHAR *pBuf)

Add an object.

alp_status_t alp_hsds_copy (AlpHsDataStoreHandle hDs, AlpLuid srcId, AlpLuid tgtId)

Copy an object.

alp_status_t alp_hsds_delete (AlpHsDataStoreHandle hDs, AlpLuid id)

Delete an object.

alp_status_t alp_hsds_is_refresh_required (AlpHsDataStoreHandle hDs, bool *pIsRequired)

alp_status_t alp_hsds_purge (AlpHsDataStoreHandle hDs)

alp_status_t alp_hsds_read (AlpHsDataStoreHandle hDs, AlpHsObjectTypePtr pTgtType, AlpLuid id, size_t offset, bool *moreData, size_t *pBufSize, _TCHAR *pBuf)

Read an object's content.

alp_status_t alp_hsds_rekey (AlpHsDataStoreHandle hDs, AlpLuid oldId, AlpLuid newId)

Assign a new id to an existing object.

alp_status_t alp_hsds_replace (AlpHsDataStoreHandle hDs, AlpHsObjectTypePtr pSrcType, AlpLuid id, size_t offset, bool moreData, size_t bufSize, const _TCHAR *pBuf)

Replace an object's content.

alp_status_t alp_hsds_update (AlpHsDataStoreHandle hDs, AlpHsObjectTypePtr pSrcType, AlpLuid id, size_t offset, bool moreData, size_t bufSize, const _TCHAR *pBuf)

Update an object's content.

Function Documentation

alp_status_t alp_hsds_add ( AlpHsDataStoreHandle hDs,

AlpHsObjectTypePtr pSrcType,

bool isReferenceable,

AlpLuid newId,

AlpLuid * pComponentIds,

size_t componentIdSize,

size_t offset,

bool moreData,

size_t bufSize,

const _TCHAR * pBuf

)

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.

Parameters:

[in] hDs Handle to an open datastore

[in] pSrcType MIME type format for the content in *pBuf

[in] isReferenceable True if the new object is refereceable; false otherwise

[in] newId The new object's id

[in] pComponentIds When the object is identified by an extended GUID, the luids for those GUIDs; otherwise NULL.

[in] componentIdSize Number of component IDs array elements, or 0 if there are none.

[in] offset The number of bytes written so far

[in] moreData True when additional calls are required to write all of the object's content; false otherwise

[in] bufSize The size of *pBuf

[in] pBuf The object's content formatted according to pSrcType

Remarks:
The Change Manager only calls this function during a synchronization session.

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

alp_status_t alp_hsds_copy ( AlpHsDataStoreHandle hDs,

AlpLuid srcId,

AlpLuid tgtId

)

Copy an object.
The HotSync Change Manager calls this function to copy an existing object's content to a new object. This is a rare operation that is only necessary when the object's current content is required for an ongoing synchronization session.

Parameters:

[in] hDs Handle to an open datastore

[in] srcId The object's id

[in] tgtId The new object's id

Remarks:
The Change Manager calls this function whenever an object's current content is required for a concurrent synchronization session. The copied content is never referenceable.

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

alp_status_t alp_hsds_delete ( AlpHsDataStoreHandle hDs,

AlpLuid id

)

Delete an object.
The HotSync Change Manager calls this function to delete an object from a DataStore.

Parameters:

[in] hDs Handle to an open datastore

[in] id The object's id

Remarks:
This Change Manager calls this function whenever it needs to delete an object from the DataStore.

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

alp_status_t alp_hsds_is_refresh_required ( AlpHsDataStoreHandle hDs,

bool * pIsRequired

)

Parameters:

[in] hDs Handle to an open datastore

Remarks:

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

alp_status_t alp_hsds_purge ( AlpHsDataStoreHandle hDs )

Parameters:

[in] hDs Handle to an open datastore

Remarks:
When a purge is requested, the datastore implementation may choose to completely rebuild its database. As a result, the ChangeMgr assumes that this call actually closes the datastore. If the call succeeds, the ChangeMgr immediately calls alp_hsds_open() to re-open the datastore.

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

alp_status_t alp_hsds_read ( AlpHsDataStoreHandle hDs,

AlpHsObjectTypePtr pTgtType,

AlpLuid id,

size_t offset,

bool * moreData,

size_t * pBufSize,

_TCHAR * pBuf

)

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.

Parameters:

[in] hDs Handle to an open datastore

[in] pTgtType How to format the object's content

[in] id The object's id

[in] offset The number of bytes read so far

[out] moreData True when additional calls are required to read all of the object's content; false otherwise

[in,out] pBufSize On input, the size of *pBuf; on output, the number of bytes written to *pBuf

[in,out] pBuf Buffer to hold the object's content

Remarks:
On input pBufSize contains the size of *pBuf in bytes. On output it should contain the number of bytes written to *pBuf.
Do not include the null terminated character at the end of content.
The Change Manager only calls this function during a synchronization session.

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

alp_status_t alp_hsds_rekey ( AlpHsDataStoreHandle hDs,

AlpLuid oldId,

AlpLuid newId

)

Assign a new id to an existing object.
The HotSync Change Manager calls this function to assign a new id to an existing object. This is a rare operation that is used to retain the object's referenceable id.

Parameters:

[in] hDs Handle to an open datastore

[in] oldId The object's current id

[in] newId The object's new id

Remarks:
The Change Manager calls this function whenever it needs to resolve a conflict in favor of a non-referenceable version of an object's content. The rekeyed content is always referenceable.

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

alp_status_t alp_hsds_replace ( AlpHsDataStoreHandle hDs,

AlpHsObjectTypePtr pSrcType,

AlpLuid id,

size_t offset,

bool moreData,

size_t bufSize,

const _TCHAR * pBuf

)

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.

Parameters:

[in] hDs Handle to an open datastore

[in] pSrcType MIME type format for content in *pBuf

[in] id The object's id

[in] offset The number of bytes written so far

[in] moreData True when additional calls are required to write all of the object's content; false otherwise

[in] bufSize The size of *pBuf

[in] pBuf The object's content formatted according to pSrcType

Remarks:
The Change Manager only calls this function during a synchronization session.

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

alp_status_t alp_hsds_update ( AlpHsDataStoreHandle hDs,

AlpHsObjectTypePtr pSrcType,

AlpLuid id,

size_t offset,

bool moreData,

size_t bufSize,

const _TCHAR * pBuf

)

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.

Parameters:

[in] hDs Handle to an open datastore

[in] pSrcType MIME type format for content in *pBuf

[in] id The object's id

[in] offset The number of bytes written so far

[in] moreData True when additional calls are required to write all of the object's content; false otherwise

[in] bufSize The size of *pBuf

[in] pBuf The object's modified content formatted pSrcType

Remarks:
The Change Manager only calls this function during a synchronization session.

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

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


Functions
alp_status_t	alp_hsds_add (AlpHsDataStoreHandle hDs, AlpHsObjectTypePtr pSrcType, bool isReferenceable, AlpLuid newId, AlpLuid pComponentIds, size_t componentIdSize, size_t offset, bool moreData, size_t bufSize, const _TCHAR pBuf)
	Add an object.
alp_status_t	alp_hsds_copy (AlpHsDataStoreHandle hDs, AlpLuid srcId, AlpLuid tgtId)
	Copy an object.
alp_status_t	alp_hsds_delete (AlpHsDataStoreHandle hDs, AlpLuid id)
	Delete an object.
alp_status_t	alp_hsds_is_refresh_required (AlpHsDataStoreHandle hDs, bool *pIsRequired)
alp_status_t	alp_hsds_purge (AlpHsDataStoreHandle hDs)
alp_status_t	alp_hsds_read (AlpHsDataStoreHandle hDs, AlpHsObjectTypePtr pTgtType, AlpLuid id, size_t offset, bool moreData, size_t pBufSize, _TCHAR *pBuf)
	Read an object's content.
alp_status_t	alp_hsds_rekey (AlpHsDataStoreHandle hDs, AlpLuid oldId, AlpLuid newId)
	Assign a new id to an existing object.
alp_status_t	alp_hsds_replace (AlpHsDataStoreHandle hDs, AlpHsObjectTypePtr pSrcType, AlpLuid id, size_t offset, bool moreData, size_t bufSize, const _TCHAR *pBuf)
	Replace an object's content.
alp_status_t	alp_hsds_update (AlpHsDataStoreHandle hDs, AlpHsObjectTypePtr pSrcType, AlpLuid id, size_t offset, bool moreData, size_t bufSize, const _TCHAR *pBuf)
	Update an object's content.

Reading and Writing Objects [API's]

Detailed Description

Functions

Function Documentation

Reading and Writing Objects
[API's]