Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

16    Category Manager Sync

System Management

Exploring Palm OS®

The Category Manager synchronization functions allow you to obtain category change tracking information.


NOTE: The APIs described in this chapter aren't generally used by Palm OS applications.

Because CatMgrSync.h only declares functions, this chapter is composed of a single section only:

Category Manager Sync Functions and Macros

The header file CatMgrSync.h declares the API that this chapter describes.

Category Manager Sync Functions and Macros ^TOP^

CatMgrSyncGetModifiedCategories Function ^TOP^

Purpose

Retrieves the ID of each modified category in a Schema database.

Declared In

CatMgrSync.h

Prototype

status_t CatMgrSyncGetModifiedCategories (
   DmOpenRef dbP,
   const DbSyncCounterType *counterP,
   CategoryID **categoriesPP,
   uint32_t *numCategoriesP
)

Parameters

dbP
DmOpenRef to an open database.
counterP
Pointer to the desktop counter.
categoriesPP
Pointer to an array of category IDs, where each identifies a category that has changed.
numCategoriesP
Pointer to a variable that receives the number of elements in categoriesPP.

Returns

Returns errNone if the category IDs were successfully retrieved, or one of the following otherwise:

catmErrInvalidParam
dbP is NULL.
dmErrNotSchemaDatabase
The specified database is not a Schema database.
catmErrMemError
A memory error occurred.

Comments

This function returns a list of categories that have a higher sync counter than the counterP parameter. That is, it returns all categories that were modified since the database had the same sync counter value as counterP. The Category Manager allocates the category ID list returned in categoriesPP; your code is responsible for freeing the list by calling CatMgrSyncReleaseStorage().

Example

The following code excerpt shows how you could use this function to retrieve a list of modified categories by ID:


DbSyncCounterType cover; 
CategoryID categoriesP; 
uint32_t numCategories; 
 
dbRef = DbOpenDatabase(dbID, dmModeReadWrite, dbShareNone,
   dbDefaultSortID); 
 
cover = 0; 
CatMgrSyncGetModifiedCategories(dbRef, &cover,&categoriesP,
   &numCategories); 
// 
// do something with the category IDs in categoriesP here 
// 
CatMgrSyncReleaseStorage(categoriesP);									 

CatMgrSyncGetPurgeCounter Function ^TOP^

Purpose

Retrieve the category purge counter for a specified database.

Declared In

CatMgrSync.h

Prototype

status_t CatMgrSyncGetPurgeCounter (
   DmOpenRef dbP,
   DbSyncCounterType *purgeCounterP
)

Parameters

dbP
DmOpenRef to an open database.
purgeCounterP
Pointer to a DbSyncCounterType variable that receives the row purge count.

Returns

Returns errNone if the category purge counter was successfully retrieved, or one of the following otherwise:

catmErrInvalidParam
dbP is NULL.
dmErrNotSchemaDatabase
The specified database is not a Schema database.
PrvLockCatMgrInfo
The specified database has no defined categories.
catmErrMemError
A memory error occurred.

CatMgrSyncReleaseStorage Function ^TOP^

Purpose

Release a dynamic heap chunk that was allocated by the Category Manager when CatMgrSyncGetModifiedCategories() is called.

Declared In

CatMgrSync.h

Prototype

status_t CatMgrSyncReleaseStorage (
   DmOpenRef dbP,
   MemPtr bufferP
)

Parameters

dbP
DmOpenRef to an open database.
bufferP
Pointer to the chunk to be released. This should only be a chunk that was allocated for you by CatMgrSyncGetModifiedCategories().

Returns

Returns errNone if the operation completed successfully, or one of the following otherwise:

catmErrInvalidParam
dbP is NULL or the specified buffer has zero length.
dmErrNotSchemaDatabase
The specified database is not a Schema database.
catmErrInvalidStoragePtr
The bufferP parameter is invalid.
memErrInvalidParam
The bufferP parameter is invalid.