Developer

API Reference

pim_AEECLSID_CalendarStore

Brew Release
Brew MP 1.0.2
Description
END:VALARM END:VEVENT END:VCALENDAR

The SearchCriteria supported by this class is defined in the following format (an empty search criterion "" will return all records) and represented using a UTF-8 encoded string:
   Search       :: [SearchClause]
   SearchClause :: 
   fieldname    :: 
   binary-op    :: =
   pattern      :: literal-value (string) 

Examples of search criteria:
   "SUMMARY=Project status meeting" - Matches all vCalendar records with SUMMARY
                   set to "Project status meeting"

   "UID=040000008200E00074C5B7101A82E00800000000100C47396304C8010000000000000
    00010000000430E90713A99A345BD3C8FF5EBBFC655" - Matches the record with 
    UID set to the specified value.

This class only supports retrieving complete records, i.e., the Offset for pim_IRecordStore_GetRecord() should always be 0. Also, pim_IRecordStore_Search() is not supported - the class does not support searching inside vCalendar records.
Some sample usage scenarios are described below (proper error handling and memory management should be handled by users of the code snippets):

Creating a pim_IRecordStore object using pim_AEECLSID_CalendarStore

   pim_IRecordStore* piCalendarStore= 0;
   int nErr;
   
   // Assumption: piEnv is a valid IEnv pointer
   nErr = IEnv_CreateInstance(piEnv, pim_AEECLSID_CalendarStore, (void **)&piCalendarStore);
   if (AEE_SUCCESS != nErr) {
      // Handle error here.
   }

Adding a record to the calendar store

   // A record can be added to the calendar record store using pim_IRecordStore 
   // interface. First, a vCalendar formatted single byte per character text
   // string should be created. Then the string can be stored in the calendar
   // store.
   int nErr;
   pim_IRecordStore *piCalendarStore;
   char *Entry;
   pim_IRecordStore_RecordID ID;


   // Assumption: piEnv is a valid IEnv pointer, and piCalendarStore points
   // to an already created instance of pim_AEECLSID_CalendarStore
   // Also, Entry points to a valid vCalendar formatted record
   nErr = pim_IRecordStore_AddRecord(piCalendarStore, Entry, 1 + std_strlen(Entry), &ID);
   if (AEE_SUCCESS != nErr) {
      // Handle error here.
   }

Deleting a record from the calendar store

   // Assumption: piCalendarStore is a valid pim_IRecordStore object 
   // and ID is the pim_IRecordStore_RecordID value obtained from a 
   // previous call to pim_IRecordStore_AddRecord(), pim_IRecordStore_Search() 
   // or pim_IRecordStore_GetChangesSince()
   int nErr;

   nErr = pim_IRecordStore_RemoveRecord(piCalendarStore, ID);
   if (AEE_SUCCESS != nErr) {
      // Handle error here.
   }

Reading a record from the calendar store based on a record ID

A record can be read from the calendar store using pim_IRecordStore interface.
   // Assumption: piCalendarStore is a valid pim_IRecordStore object 
   // and ID is the pim_IRecordStore_RecordID value obtained from a 
   // previous call to pim_IRecordStore_AddRecord(), pim_IRecordStore_Search() 
   // or pim_IRecordStore_GetChangesSince()
   char* Entry;
   int EntryLen = 0;
   int EntryLenReq = 0;

   // Create a baseline for future comparisons.
   nErr = pim_IRecordStore_GetRecord(piCalendarStore, 
                                     RecordID, 0, 
                                     Entry, EntryLen, &EntryLenReq);
   if (AEE_SUCCESS != nErr) {
      // Handle error here.
   }

   // Remember to deallocate using IENV_FREEIF() after done using Entry.
   nErr = IEnv_ErrMallocNoZI(piEnv, EntryLenReq, (void **)Entry);
   if (AEE_SUCCESS != nErr) {
      // Handle error here.
   }
   EntryLen = EntryLenReq;

   nErr = pim_IRecordStore_GetRecord(piCalendarStore, 
                                     RecordID, 0, 
                                     Entry, EntryLen, &EntryLenReq);
   if (AEE_SUCCESS != nErr) {
      // Handle error here.
   }


Finding records based on certain search criteria

Calendar records can be obtained based on supported search criteria. One example is searching for a meeting or event by title.
   // Assumption: piCalendarStore is a valid pim_IRecordStore object
   int nErr;
   pim_IRecordStore_RecordID* IDs = NULL;
   int IDsLen = 0;
   int IDsLenReq = 0;
   unsigned char* pszSearchCriteria = "SUMMARY=Project status meeting"; 
                                                    // Matches all records with 
                                                    // vCal SUMMARY set to
                                                    // "Project status meeting"

   nErr = pim_IRecordStore_Search(piCalendarStore, 
                                  pszSearchCriteria, 
                                  std_strlen((char*)pszSearchCriteria) + 1,
                                  IDs, IDsLen, &IDsLenReq);
   if (AEE_SUCCESS != nErr) {
      // Handle error here.
   }

   // Remember to deallocate using IENV_FREEIF() after done using IDs.
   nErr = IEnv_ErrMallocNoZI(piEnv, IDsLenReq, (void **)IDs);
   if (AEE_SUCCESS != nErr) {
      // Handle error here.
   }
   IDsLen = IDsLenReq;

   nErr = pim_IRecordStore_Search(piCalendarStore, 
                                  pszSearchCriteria, 
                                  std_strlen(pszSearchCriteria) + 1,
                                  IDs, IDsLen, &IDsLenReq);
   if (AEE_SUCCESS != nErr) {
      // Handle error here.
   }

   // Read record using pim_IRecordStore_GetRecord() as show in 
   // "Reading a record from the calendar store based on a record ID" 
   // section.

Registering for notification on changes in calendar records

Registering for notifications on changes in calendar records can be done by simply using the pim_IRecordStore_OnChange() API, but for efficiently determining the type of changes (add, delete, update etc), it is recommended that the client maintain a list of records it has already seen to be compared with the list returned by pim_IRecordStore_GetChangesSince() API. This will also help the client in finding the changes if it is not memory resident. A sequence diagram below also depicts how to use the sequence number to easily find out changes that happened to the calendar records.
   // Assumption: piCalendarStore is a valid pim_IRecordStore object, 
   // piSignal is a valid ISignal object and piEnv is a valid Env object.
   int64 SeqNum = 0LL;
   int64 CurrentSeqNum = 0LL;
   pim_IRecordStore_RecordID* AddedIDs = NULL;
   int AddedIDsLen = 0;
   int AddedIDsLenReq = 0;
   pim_IRecordStore_RecordID* UpdatedIDs = NULL;
   int UpdatedIDsLen = 0;
   int UpdatedsLenReq = 0;
   pim_IRecordStore_RecordID* DeletedIDs = NULL;
   int DeletedIDsLen = 0;
   int DeletedLenReq = 0;
   IQI* piQI = NULL;

   // If application stored the SeqNum in persistent storage from it's last 
   // execution (this is recommended; as is storing the record IDs of the last 
   // snapshot that the application knew about), read it and use that as SeqNum. 
   // Then update the baseline for future comparisons.
   nErr = pim_IRecordStore_GetChangesSince(piCalendarStore, 
                                           &CurrentSeqNum, SeqNum,
                                           AddedIDs, AddedIDsLen, &AddedIDsLenReq,
                                           UpdatedIDs, UpdatedIDsLen, &UpdatedsLenReq,
                                           DeletedIDs, DeletedIDsLen, DeletedLenReq,
                                           NULL, 0, 0);
   if (AEE_SUCCESS != nErr) {
      // Handle error here. Be sure to handle pim_IRecordStore_ESTALESEQNUM 
      // error code.
      if (pim_IRecordStore_ESTALESEQNUM == nErr) {
         // Provide valid input for UnchangedIDs and compare them with previous
         // snapshot of record IDs to find out deleted records.
      }
   }
   SeqNum = CurrentSeqNum; // Update your baseline

   // Remember to deallocate using IENV_FREEIF() after done using AddedIDs.
   nErr = IEnv_ErrMallocNoZI(piEnv, AddedIDsLenReq, (void **)&AddedIDs);
   if (AEE_SUCCESS != nErr) {
      // Handle error here.
   }
   AddedIDsLen = AddedIDsLenReq;

   // Remember to deallocate using IENV_FREEIF() after done using UpdatedIDs.
   nErr = IEnv_ErrMallocNoZI(piEnv, UpdatedIDsLenReq, (void **)&UpdatedIDs);
   if (AEE_SUCCESS != nErr) {
      // Handle error here.
   }
   UpdatedIDsLen = UpdatedIDsLenReq;

   // Remember to deallocate using IENV_FREEIF() after done using DeletedIDs.
   nErr = IEnv_ErrMallocNoZI(piEnv, DeletedIDsLenReq, (void **)&DeletedIDs);
   if (AEE_SUCCESS != nErr) {
      // Handle error here.
   }
   DeletedIDsLen = DeletedIDsLenReq;

   nErr = pim_IRecordStore_GetChangesSince(piCalendarStore, 
                                           &CurrentSeqNum, SeqNum,
                                           AddedIDs, AddedIDsLen, &AddedIDsLenReq,
                                           UpdatedIDs, UpdatedIDsLen, &UpdatedsLenReq,
                                           DeletedIDs, DeletedIDsLen, DeletedLenReq,
                                           NULL, 0, 0);
   if (AEE_SUCCESS != nErr) {
      // Handle error here. Be sure to handle pim_IRecordStore_ESTALESEQNUM 
      // error code.
      if (pim_IRecordStore_ESTALESEQNUM == nErr) {
         // Provide valid input for UnchangedIDs and compare them with previous
         // snapshot of record IDs to find out deleted records.
      }
   }

   nErr = pim_IRecordStore_OnChange(piCalendarStore, piSignal, 
                                    pim_IRecordStore_Action_Commit, &piQI);
   if (AEE_SUCCESS != nErr) {
      // Handle error here.
   }

   // For efficiency reasons, it is recommened that SeqNum and record IDs be 
   // stored in persistent storage so that the next time the application is 
   // started, these values can be used as the baseline.

Additionally, the following sequence diagram depicts how a client may use the sequence number information to efficiently find out what changes occurred in the calendar record store.
Application                                                               System
       |                                                                    |
       |                                                                    |
    1) |--> pim_IRecordStore_GetChangesSince() with baseline seq num   ---->|
       |<-- Baseline seq num should either be read from persistent storage -|
       |--- or can be 0 for the very first time. It is recommended that  ---|
       |--- sequence number and record IDs be stored in persistent storage -|
       |--- so that the application can use those values for their most  ---|
       |--- recent baseline snapshot to enhance efficiency.              ---|
    2) |<-- Current seq num and snapshot of current record identifiers <----|
       |--- Client remembers new seq num obtained from this call to use  ---|
       |--- in next call to pim_IRecordStore_GetChangesSince()           ---|
       |--- Client remembers snapshot of record identifiers e.g. {1,2,3} ---|
    3) |-----------------> pim_IRecordStore_OnChange()  ------------------->|
       |                               .                                    |
       |                               .                                    |
       |                               .                                    |
    4) |<---------- Calendar store got changed and Signal is set  <---------|
    5) |--> pim_IRecordStore_GetChangesSince() with seq num from step 2 --->|
    6) |<-- Current seq num and snapshot of current record identifiers <----|
       |--- Client obtains list of added, updated and deleted record IDs. --|
       |--- Client remembers snapshot of record identifiers based on -------|
       |--- list of added and updated IDs. e.g. {1,3,4,5}                ---|
    7) |---------> pim_IRecordStore_GetRecord() with record IDs 1,3,4,5 --->|
       |--- Client goes to sleep/gets terminated.                        ---|
       |                               .                                    |
       |                               .                                    |
       |                               .                                    |
       |--- Client wakes up.                                             ---|
    8) |--> pim_IRecordStore_GetChangesSince() with seq num from step 5 --->|
    9) |<---- pim_IRecordStore_ESTALESEQNUM. Maybe many changes have     ---|
       |--- happened to calendarstore.                                 <----|
       |--- Client prepares for "slow sync" by providing valid values for --|
       |--- AddedIDs, UpdatedIDs and UnchangedIDs.                       ---|
   10) |--> pim_IRecordStore_GetChangesSince() with valid AddedIDs,      ---|
       |--- UpdatedIDs and UnchangedIDs.                    --------------->|
   11) |<-- Current seq num and snapshot of current record identifiers <----|
       |--- Client compares added, updated and unchanged record IDs with ---|
       |--- previous snapshot to find out records that were deleted.     ---|
       |--- Client remembers new seq num obtained from this call to use  ---|
       |--- in next call to pim_IRecordStore_GetChangesSince()           ---|

Default Interface Name
  • Follow