The Category Manager synchronization functions allow you to obtain category change tracking information.
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
CatMgrSyncGetModifiedCategories Function
Purpose
Retrieves the ID of each modified category in a Schema database.
Declared In
CatMgrSync.h
Prototype
status_t CatMgrSyncGetModifiedCategories ( DmOpenRefdbP
, 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
isNULL
. -
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
Purpose
Retrieve the category purge counter for a specified database.
Declared In
CatMgrSync.h
Prototype
status_t CatMgrSyncGetPurgeCounter ( DmOpenRefdbP
, 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
isNULL
. -
dmErrNotSchemaDatabase
- The specified database is not a Schema database.
-
PrvLockCatMgrInfo
- The specified database has no defined categories.
-
catmErrMemError
- A memory error occurred.
CatMgrSyncReleaseStorage Function
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 ( DmOpenRefdbP
, MemPtrbufferP
)
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
isNULL
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.