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

Developer

API Reference

PIM_ICALLHISTORYUTIL

Brew Release
Brew MP 1.0.2
See Also
Description
This interface provides utility methods for Call History clients to convert from structured call history records to sequence of octets for use with pim_IRecordStore interface. This interface should be used in conjunction with the Call History class implementation for pim_IRecordStore interface.
Usage
The pim_ICallHistory interface should be used in conjunction with pim_IRecordStore interface. Typical usage will involve the following:

Creating a pim_IRecordStore record from pim_ICallHistoryUtil_Record

   // Create instances of pim_ICallHistoryUtil and pim_IRecordStore
   // Basic CallHistory record:
   pim_ICallHistoryUtil_Field CHRecord[3];   // Example with just 3 fields

   // Field 1 - CallType. Mandatory
   (void)std_strlcpy(CHRecord[0].FieldName, "CallType", pim_ICallHistoryUtil_FieldNameSize);
   CHRecord[0].ValueType = pim_ICallHistoryUtil_ValueNum;
   CHRecord[0].FieldValueNum = pim_CallHistory_CallType_From;

   // Field 2 - TimeStamp
   (void)std_strlcpy(CHRecord[1].FieldName, "TimeStamp", pim_ICallHistoryUtil_FieldNameSize);
   CHRecord[1].ValueType = pim_ICallHistoryUtil_ValueNum;
   CHRecord[1].FieldValueNum = 1234567;

   // Field 3 - Number
   (void)std_strlcpy(CHRecord[2].FieldName, "Number", pim_ICallHistoryUtil_FieldNameSize);
   CHRecord[2].ValueType = pim_ICallHistoryUtil_ValueStr;
   IEnv_ErrMallocNoZI(me->piEnv, 13, (void **)&(CHRecord[2].FieldValueStr)); // Handle error
   (void)std_strlcpy(CHRecord[2].FieldValueStr, "\"8885551234\"", 13);
   CHRecord[2].FieldValueStrLen = 13;
   CHRecord[2].FieldValueStrLenReq = 13;

   unsigned char* RSRecord = 0;
   int RSRecordLen = 0;
   int RSRecordLenReq = 0;

   if (AEE_SUCCESS == pim_ICallHistoryUtil_CreateRecord(me, &CHRecord, STD_ARRAY_SIZE(CHRecord), RSRecord, RSRecordLen, &RSRecordLenReq)) {
      RSRecordLen = RSRecordLenReq * sizeof(unsigned char);
      if (AEE_SUCCESS != IEnv_ErrMalloc(me->piEnv, RSRecordLen, (void **)&RSRecord)) { // Remember to deallocate this
         // Handle error
      }

      if (AEE_SUCCESS == pim_ICallHistoryUtil_CreateRecord(me, &CHRecord, STD_ARRAY_SIZE(CHRecord), RSRecord, RSRecordLen, &RSRecordLenReq)) {
         pim_IRecordStore_RecordID RecordID;
         pim_IRecordStore_AddRecord(_pif, RSRecord, RSRecordLen, &RecordID); //Handle return value
      } else {
         // Handle failure
      }
      IENV_FREEIF(me->piEnv, RSRecord);
   } else {
      // Handle failure
   }

   IENV_FREEIF(me->piEnv, CHRecord[2].FieldValueStr);
   

Extracting pim_ICallHistoryUtil_Field entries from pim_IRecordStore record

   // Create instance of pim_ICallHistoryUtil
   // Basic CallHistory record:
   pim_ICallHistoryUtil_Iterator Itr;
   if (AEE_SUCCESS != pim_ICallHistoryUtil_CreateIterator(me, RSRecord, RSRecordLen, &Itr)) {
      // Handle failure
   }

   int nNumFields;
   if (AEE_SUCCESS != pim_ICallHistoryUtil_GetNumFields(me, Itr, &nNumFields)) {
      // Handle failure
   }

   pim_ICallHistoryUtil_CallHistoryRecord* CHRecord = (pim_ICallHistoryUtil_CallHistoryRecord *)MALLOC(nNumFields * sizeof(pim_ICallHistoryUtil_Field)); // Remember to FREE() this

   for (int i = 0; i < nNumFields, i++) {
      char FieldName[pim_ICallHistoryUtil_FieldNameSize];
      pim_ICallHistoryUtil_FieldValueType ValueType;
      int nFieldNameSizeReq = 0;

      if (AEE_SUCCESS != pim_ICallHistoryUtil_GetNextField(me, Itr, FieldName, pim_ICallHistoryUtil_FieldNameSize, &nFieldNameSizeReq, &ValueType)) {
         // Handle failure
      }

      STRLCPY(CHRecord[i].FieldName, FieldName, pim_ICallHistoryUtil_FieldNameSize);
      CHRecord[i].ValueType = ValueType;

      if (pim_ICallHistoryUtil_ValueNum == ValueType) {
         int nValue = 0;
         if (AEE_SUCCESS != pim_ICallHistoryUtil_GetNextValueNum(me, Itr, &nValue)) {
            // Handle failure
         }

         CHRecord[i].FieldValueNum = nValue;
      } else if (pim_ICallHistoryUtil_ValueStr == ValueType) {
         char* FieldValueStr = NULL;
         int FieldValueStrLen = 0;
         int FieldValueStrLenReq = 0;

         // Make sure to allocate enough space in FieldValueStr to accomodate FieldValueStrLenReq items
         if (AEE_SUCCESS != pim_ICallHistoryUtil_GetNextValueStr(me, Itr, FieldValueStr, FieldValueStrLen, &FieldValueStrLenReq)) {
            // Handle failure
         }

         // Make sure to allocate enough space in CHRecord[i].FieldValueStr to accomodate FieldValueStrLenReq items
         STRLCPY(CHRecord[i].FieldValueStr, FieldValueStr, sizeof(CHRecord[i].FieldValueStr);
         CHRecord[i].FieldValueStrLen = FieldValueStrLen;
         CHRecord[i].FieldValueStrLenReq = FieldValueStrLenReq;
      }
   }   

   pim_ICallHistoryUtil_DeleteIterator(me, Itr);
   // Be sure to FREE() any CHRecord[i].FieldValueStr fields that were allocated using MALLOC()
   // Be sure to FREE() CHRecord after done using it