A message store is the "root" object that will be used by MAPI for a specific mail transport instance. Pocket PC contains a default message store that is used by ActiveSync when you synchronize with a connected desktop, and additional message stores are created automatically whenever a new MAPI transport is configured on the device. For example, when you create a new connection to a POP3 mail server, a new message store is created to handle the MAPI objects related to that connection.
Each message store provides the storage mechanism as well as the hierarchy model for objects contained within it. This includes all of the tables, messages, folders, and attachments for a specific mail configuration.
The MAPI message store object is implemented by the IMsgStore interface, and supports the methods described in Table 11.14.
Method | Description |
---|---|
Advise() | Sets up an IMAPIAdviseSink interface that receives notification events for the message store |
GetReceiveFolder() | Returns the ENTRYID for the folder that was specified to receive incoming messages |
OpenEntry() | Returns an interface for a specific MAPI object based on its ENTRYID |
Unadvise() | Cancels a notification event sink that was set up with a previous call to IMsgStore::Advise() |
The IMsgStore interface is derived from IMAPIProp, and supports the properties described in Table 11.15 for each message store.
Property Tag | Property Type | Description |
---|---|---|
PR_CE_IPM_DRAFTS_ENTRYID | PT_BINARY | The entry identifier for the Drafts folder |
PR_CE_IPM_INBOX_ENTRYID | PT_BINARY | The entry identifier for the Inbox folder |
PR_DISPLAYNAME | PT_TSTRING | The display name of the object |
PR_ENTRYID | PT_BINARY | The object's entry identifier |
PR_IPM_OUTBOX_ENTRYID | PT_BINARY | The entry identifier for the Outbox folder of the store |
PR_IPM_SENTMAIL_ENTRYID | PT_BINARY | The entry identifier for the Sent Items folder of the store |
PR_IPM_SUBTREE_ENTRYID | PT_BINARY | The entry identifier for the root folder of the store |
PR_IPM_WASTEBASKET_ENTRYID | PT_BINARY | The entry identifier for the Deleted Items folder of the store |
PR_LAST_MODIFICATION_TIME | PT_SYSTIME | The last date and time the object was modified |
PR_NULL | PT_NULL | A NULL value |
PR_OBJECT_TYPE | PT_LONG | The type of object |
To open a specific message store, you need to use the IMAPISession::OpenMsgStore() function and provide it with the ENTRYID of the store you want to use. Because the ENTRYID might not be persistent (depending on the message store), you will usually have to get the table of message stores from the current MAPI session first, and look for the entry you are interested in. This can be accomplished by using the IMAPISession::GetMsgStoresTable() function.
The following example shows how you can open a message store that has the name POP3. This requires you to perform several actions to find the proper ENTRYID for the message store you are interested in:
// Open up the POP3 inbox by getting a list of message // Stores IMAPITable *pIMapiStoresTable = NULL; hr = pIMapi->GetMsgStoresTable(0, &pIMapiStoresTable); if(FAILED(hr)) return FALSE; // Query the table. We need the ENTRY_ID and DISPLAY_NAME // for the store IMsgStore *pPop3Store = NULL; while(1) { SRowSet *pRowSet = NULL; SizedSPropTagArray(2, tblColumns) = {2,{PR_DISPLAY_NAME, PR_ENTRYID}}; pIMapiStoresTable->SetColumns((LPSPropTagArray) &tblColumns, 0); hr = pIMapiStoresTable->QueryRows(1, 0, &pRowSet); if(pRowSet->cRows != 1) break; // Compare the name with "POP3" if(_tcscmp(TEXT("POP3"), pRowSet->aRow[0].lpProps[0].Value.lpszW) == 0) { ENTRYID *pEntry = (ENTRYID *)pRowSet->aRow[0]. lpProps[1].Value.bin.lpb; ULONG ulStoreBytes = pRowSet->aRow[0].lpProps[1]. Value.bin.cb; hr = pIMapi->OpenMsgStore(NULL, ulStoreBytes, pEntry, NULL, NULL, &pPop3Store); MAPIFreeBuffer(pRowSet->aRow); MAPIFreeBuffer(pRowSet); break; } // Free buffers allocated by MAPI MAPIFreeBuffer(pRowSet->aRow); MAPIFreeBuffer(pRowSet); }; // Did it open? if(!pIMapi) return FALSE; // Open the Inbox folder LPSPropValue rgprops = NULL; LPSPropValue lppPropArray = NULL; ULONG cValues = 0; IMAPIFolder *pPOPInboxFolder = NULL; SizedSPropTagArray(2, rgTags) = {2,{PR_CE_IPM_INBOX_ENTRYID,PR_OBJECT_TYPE}}; // Now get the Inbox folder. hr = pPop3Store->GetProps((LPSPropTagArray)&rgTags, MAPI_UNICODE, &cValues, &rgprops); if(FAILED(hr)) { // Remember to clean up return FALSE; } hr = pPop3Store->OpenEntry(rgprops[0].Value.bin.cb, (LPENTRYID)rgprops[0].Value.bin.lpb, NULL, MAPI_MODIFY, NULL, (LPUNKNOWN*)&pPOPInboxFolder); // pPOPInboxFolder should now point to the inbox..
As you can see from the example, after you have logged into a MAPI session, you call into the IMAPISession::GetMsgStoresTable() function to get the list of available stores on the device. Because you are interested only in the store name and its entry identifier, you set the columns that you need by using the IMAPITable::SetColumns() function to return only the PR_DISPLAY_NAME and PR_ENTRYID properties. Next, you use the IMAPITable::QueryRows() function on the returned message store table to return a single object at a time.
After the object data has been returned to you, you can check the entry to see if it is the POP3 message store. Once you find it, you can use the ENTRYID to open the proper message store by using either the IMsgStore::OpenEntry() or IMAPISession::OpenEntry() functions.