API Reference | developer.brewmp.com API Reference | developer.brewmp.com

Developer

API Reference

PIM_IRECORDSTORE_ONCHANGE()

Brew Release
Brew MP 1.0.2
See Also
pim_IRecordStore_GetChangesSince() pim_IRecordStore Error Codes
Description
This function allows the client to specify a signal object that will be set when the specified action takes place on the underlying record store. The following actions are supported:
   pim_IRecordStore_Action_Add         Signal fires when a new record is 
                                       added
   pim_IRecordStore_Action_Delete      Signal fires when a record is deleted
   pim_IRecordStore_Action_Update      Signal fires whan an existing record 
                                       is updated
   pim_IRecordStore_Action_Writeable   Signal fires whan record store becomes 
                                       writeable
   pim_IRecordStore_Action_Readable    Signal fires whan record store becomes 
                                       readable

When accessing a shared record store for reading or writing, the caller would first register a signal with pim_IRecordStore_Action_Readable or pim_IRecordStore_Action_Writeable action types, then execute APIs that read or write to the record store. If the API fails with an AEE_EWOULDBLOCK error, the caller would wait for the registered signal to get set before retrying the API.
A change sequence number is updated in the record store so that the client can determine what changes have occurred when the signal fires. Here are the recommended steps for incrementally determining what changes have occurred in the record store:
1. Call pim_IRecordStore_GetChangesSince() and save the returned values to create a baseline. 2. Register a signal through the pim_IRecordStore_OnChange() method. 3. When the signal fires, call pim_IRecordStore_GetChangesSince() with the baseline values and save the returned sequence number and record snapshot as the new baseline.
Interface
Prototype
  •    AEEResult pim_IRecordStore_OnChange(pim_IRecordStore* _pif, ISignal* Signal, 
                                           pim_IRecordStore_ActionType action, IQI** ireg)
    
Return
  • AEE_SUCCESS on successful notification registration
    Error code otherwise
Side Effect
  • None.
Comments
It is the caller's responsibility to release the registration object once they are no longer interested in the notification associated with the object.