Enumerating Objects
A version of this page is also available for
4/8/2010
Enumeration is the process of accessing every object in a directory or folder to determine whether the object has changed and whether changed objects meet the selection criteria.
- The service manager calls IReplStore::IsFolderChanged.
- If IReplStore::IsFolderChanged returns TRUE, the service manager calls IReplStore::FindFirstItem.
- If additional objects exist, IReplStore::FindFirstItem sets *pfExist to TRUE.
- The service manager calls IReplStore::FindNextItem repeatedly until *pfExist is FALSE, which indicates there are no more objects to be enumerated.
- The service manager calls IReplStore::FindItemClose to free any resources that were used during enumeration.
The following code example shows how to implement IReplStore::FindFirstItem.
STDMETHODIMP CStore::FindFirstItem
(
HREPLFLD hFolder, // Handle to a folder
HREPLITEM *phItem, // Output pointer to the handle of the first
// item in the folder
BOOL *pfExist // Output pointer to a Boolean value that is set
// to TRUE if there is an object in the folder
)
{
CFolder *pFolder = (CFolder*)hFolder;
// Find the first item.
// pItem in the following code points to the first item.
// ...
// Implementation retrieves the unique identifier from the first item.
// pItem->m_uid = retrieved_unique_ID;
// Implementation retrieves whatever it uses to verify the first item
// has changed; for example, a time stamp.
// pItem->m_ftModified = retrieved_time_stamp;
*phItem = (HREPLITEM)pItem;
if (pfExist)
*pfExist = TRUE;
return NOERROR;
}
During enumeration, you can select just those objects you want to synchronize by having the desktop provider return to the service manager only those that meet your criteria. For example, you might want to synchronize only appointments that fall within the next three days. The service manager accesses the selection criteria — which are stored with the folder handle — by calling IReplStore::IsItemReplicated.
Important
Any object not returned by the enumeration appears as a deleted desktop object. The service manager assumes the object has been deleted and deletes the corresponding device object. To avoid deleting objects that do not meet the selection criteria, be sure the desktop provider's enumeration returns every object in the store whether or not the object meets the selection criteria.
You can reselect as conditions change. For example, you might want to synchronize appointments falling within the next three days, every day. In order to determine the date range to select for, the service manager calls IReplStore::ReportStatus with RSC_DATE_CHANGED to initiate the synchronization process.