Working with Message Stores

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.

Table 11.14. IMsgStore Methods

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.

Table 11.15. IMsgStore Properties

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.