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

Developer

API Reference

PIM_IMESSAGESTORE

Brew Release
Brew MP 1.0.2
See Also
None
Description
pim_IMessageStore interface provides an API to store, retrieve, and manipulate MMS, SMS and EMS messages stored locally in a wireless device. It allows applications to enumerate messages in different folders. It optionally supports user-defined folders in additional to common pre-defined ones. It allows implementation to support additional message/folder attributes. pim_IMessageStore relies on the pim_IRecordStore API for notification and synchronization. To support such features, the class implementing the pim_IMessageStore should also implements the pim_IRecordStore API.
Usage
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_IMessageStore object using pim_AEECLSID_MessageStore


   pim_IMessageStore* piMsgStore = NULL;
   int nErr;
   
   // Assumption: piEnv is a valid IEnv object pointer
   nErr = IEnv_CreateInstance(piEnv, pim_AEECLSID_MessageStore, (void **)&piMsgStore);
   if (AEE_SUCCESS != nErr) {
      // Handle error here.
   }
   

Adding a new CDMA SMS to folder INBOX


   a. Create an instance of pim_IMessageStore
 
   b. Convert the message into OTA format (TBD)
 
   c. Get all the folders in the store (assume only flat folder structure)
 
   nErr = pim_IMessageStore_GetSubFolderIDs(piMsgStore, pim_IMessageStore_FOLDER_ID_ROOT, pBuf, nBufSize, &nBufSizeReq);
   if (AEE_SUCCESS == nErr && nBufSize < nBufSizeReq) {
      // reallocate the buffer for nBufSizeReq
      // Get the folder IDs again.
   }
 
   d. For each folder in the store, compare the name to "INBOX"
 
   pim_IMessageStore_MsgFolderID nInboxID;
   boolean bFound = FALSE;
   char folderAttrStr[80];
   pim_IMessageStore_MsgFolderID i;
   
   for (i = 0; i < nBufSizeReq; i++) {

      nErr = pim_IMessageStore_GetFolderInfo(piMsgStore, i, folderAttrStr, sizeof(folderAttrStr), NULL);
      if (AEE_SUCCESS == nErr) {
         char folderName[20];
         // extract the value for the pim_FOLDER_NAME_KEY attribute from the folder attribute string
         if (0 == std_strcmp(folderName, pim_MessageStore_FOLDER_NAME_INBOX, sizeof(pim_MessageStore_FOLDER_NAME_INBOX))) {
            bFound = TRUE;
            nInboxID = i;
            break;
         }   
      }
   }
 
   if (bFound) {  
      int nMsgID;
      char msgAttrStr[200];
      
      // construct the message attribute string msgAttrStr
      // category=SMS_CDMA;type=DELIVERY;folderID=nInboxID;flags=;
 
      nErr = pim_IMessageStore_AddMsg(piMsgStore, pMsg, nMsgSize, msgAttrStr, &nMsgID);
   }


Finding unread messages in INBOX


   a. Find the INBOX folder ID as above.
 
   b. Get all messages in the folder.
 
   pim_IMessageStore_MessageID bufMID[100];
   pim_IMessageStore_MessageID i;
   int nLen;
   char msgAttrStr[200];
 
   nErr = pim_IMessageStore_GetMsgIDsbyFolder(piMsgStore, nInboxID, bufMID, STD_ARRAY_SIZE(bufMID), &nLen);
  
   if (AEE_SUCCESS == nErr) {
      for (i = 0; i < nLen; i++) {
         nErr = pim_IMessageStore_ReadMsg(piMsgStore, i, NULL, 0, NULL, msgAttrStr, sizeof(msgAttrStr), NULL);
         if (AEE_SUCCESS == nErr) {
            boolean bReadFlagPresent
            // extract the value for flags attribute
            if (!bReadFlagPresent) { 
               // FOUND UNREAD message
            }    
         }
      }
   }


Synchronization and Notification


   a. Create instance of Message Store
 
   b. QueryInterface for pim_IRecordStore
   pim_IRecordStore* piRecordStore = NULL;
 
   pim_IMessageStore_QueryInterface(piMsgStore, pim_AEEIID_IRecordStore, (void**)&piRecordStore);
 
   c. Usual pim_IRecordStore based synchronization and notification.