Enumerating Objects

Enumeration is the process of accessing each object in a directory or folder to determine whether it has changed and whether it meets any specified filtering criteria. The enumeration process is as follows:

1. The service manager calls IReplStore::IsFolderChanged.
2. If IReplStore::IsFolderChanged returns TRUE, the service manager calls IReplStore::FindFirstItem.
3. If additional objects exist, IReplStore::FindFirstItem sets *pfExist to TRUE.
4. The service manager calls IReplStore::FindNextItem repeatedly until *pfExist is FALSE, which indicates that there are no more objects.
5. The service manager calls IReplStore::FindItemClose to free any resources that were used during enumeration.

Note If an enumeration takes more than a few seconds to complete, you can use IReplNotify::SetStatusText to have the desktop provider module display text that notifies the user how much time remains until completion.

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 used in the following code points to 
    // the first item.

// ...

    // Implementation should retrieve a unique identifier from 
    // the first item.
    // pItem->m_uid = retrieved_unique_ID;

    // Implementation also should retrieve whatever it is using to         // verify if the first item is changed; for example, a time stamp.
    // pItem->m_ftModified = retrieved_time_stamp;

    *phItem = (HREPLITEM)pItem;

    if ( pfExist )
        *pfExist = TRUE;

    return NOERROR;
}

You can use the desktop provider module to filter synchronization objects during enumeration by returning to the service manager only those objects that meet your filtering criteria. For example, you may want to synchronize only appointments that fall within the next three days. The service manager accesses the filtering criteria—which is stored with the folder handle—by calling IReplStore::IsItemReplicated.

Note If a filter is implemented incorrectly, any object that fails the filter criteria appears as a deleted object on the desktop. If the desktop enumeration does not return the object, the service manager assumes that the object is deleted and deletes the corresponding device object. To avoid this, be sure that the desktop provider module returns every object in the store during enumeration.

You can reapply a filter as certain conditions change. For example, you may want to synchronize the appointments falling within the next three days, everyday. This would mean that the date criteria for the filter would change as the days pass. In order to determine exactly what date range to filter for, the service manager calls IReplStore::ReportStatus with RSC_DATE_CHANGED to initiate the synchronization process.