Enumerating Objects with the FindObjects Function
A version of this page is also available for
4/8/2010
The optional developer-implemented FindObjects device function supports synchronization of database volumes. You can directly enumerate all the objects you want to synchronize and return a list of their object IDs to the ActiveSync manager. If you synchronize more than one volume, you need to return a separate list for each volume.
The following is the prototype for FindObjects.
typedef HRESULT (*PFINDOBJECTS)(PFINDOBJINFO);
The following is the definition of FINDOBJINFO structure used by the function.
#define FO_MORE_VOLUME ((UINT)0x00000001)
#define FO_DONE_ONE_VOL ((UINT)0x00000002)
typedef struct tagFindObjInfo
{
UINT uFlags; // see FO_ definitions
OBJTYPENAME szObjType; // object type to enumerate
UINT *pOid; // pointer to list of object IDs
// Unchanged objects first in list, changed objects follow.
UINT cUnChg; // # of unchanged object IDs in list
UINT cChg; // # of changed object IDs in list
LPBYTE lpbVolumeID; // ID of volume where objects live;
// NULL if objects in RAM.
UINT cbVolumeID; // volumme size in bytes
LPVOID lpvUser; // anything provider wants in this variable
} FINDOBJINFO, *PFINDOBJINFO;
FindObjects is called at least twice after each connection. On the first call, the ActiveSync manager sets uFlags to 0. The provider enumerates all objects it synchronizes and returns a list of object IDs, pointed to by pOid. cUnChg indicates how many object IDs at the start of the list are for unchanged objects. cChg specifies how many object IDs remain in the list, all of which are for changed objects. The cbVolumeID and lpbVolumeID together specify which volume these objects are in.
If there are more objects or more volumes to be returned, the service provider should set FO_MORE_VOLUME in the uFlags before returning.
After this call has returned, the ActiveSync manager saves the list of object IDs and calls FindObjects again, this time with FO_DONE_ONE_VOL set in uFlags. This allows the service provider to release any resources used in the previous call.
The service provider can return more than once using the same volume ID. Multiple returns are required if the service provider cannot allocate enough memory for the full list of object IDs.
A volume ID does not have to be the database volume. Desktop objects can be divided among multiple volumes, including those on a PC or Compact Flash card. When a card is removed, FindObjects does not return its volume ID, so the card is considered inactive. Changes or deletions made to the desktop objects belonging to that volume are not synchronized until the card is reinserted and the volume becomes active again.
See Also
Concepts
Design Guidelines for ActiveSync Synchronization Service Providers