[This is now documented here: http://msdn.microsoft.com/en-us/library/cc979231.aspx ]
This is the third part of a three part series documenting the MFCMAPI sample add-in CreateOutlookItemsAddin. We're in the process of updating the MAPI documentation and these articles are a preview of some of the new content. This article assumes you have downloaded the add-in from the above link and are running it inside the current version of MFCMAPI. Feedback on the article and on the code is especially welcome.
Sending an Outgoing Message Requesting a Read Receipt
To create and send an message requesting a read receipt
- Create an outgoing message. See Handling an Outgoing Message.
- Add the PR_READ_RECEIPT_REQUESTED property and set it to true.
- Add the PR_CONVERSATION_INDEX property.
- Add the PR_REPORT_TAG property.
- Submit the message by calling IMessage::SubmitMessage.
MFCMAPI demonstrates these steps with the AddMail function. AddMail takes numerous parameters from the Add Mail dialog box that is displayed when the user selects Add Mail on the Addins menu in MFCMAPI. The DisplayAddMailDialog method in Mail.cpp displays the dialog box and passes values from the dialog box to the AddMail method. The DisplayAddMailDialog method does not relate directly to creating a mail item using MAPI, so it is not listed here. The AddMail method is listed below. Note that the first parameter passed to the AddMail method is a pointer to an IMAPIFolder interface. Given lpFolder that represents an IMAPIFolder interface, the code calls IMAPIFolder::CreateMessage. The CreateMessage method returns a success code and a pointer to a pointer to an IMessage interface. Most of the AddMail function code handles the work of property setting in preparation for IMAPIProp::SetProps. If the SetProps call succeeds, IMAPIProp::SaveChanges commits the changes to the store and creates a new mail item. Then, if requested, IMessage::SubmitMessage is called to send the message.
AddMail uses two helper functions to build values for the PR_CONVERSATION_INDEX and PR_REPORT_TAG properties. These functions are named BuildConversationIndex and AddReportTag, respectively. BuildConversationIndex, located in CreateOutlookItemsAddin.cpp, does the same work that the built in MAPI function ScCreateConversationIndex when a parent isn’t passed. The format of the conversation index buffer which it generates is documented in [MS-OXOMSG].pdf, section 18.104.22.168, PidTagConversationIndex. AddReportTag, located in Mails.cpp, in turn calls BuildReportTag to build a structure for PR_REPORT_TAG. This structure is documented in [MS-OXOMSG].pdf, section 22.214.171.124.19, PidTagReportTag.