Handling an Incoming Message

An incoming message is a message that has been sent across one or more messaging systems. It may have been sent only to you or to many other recipients. Incoming messages are placed in a receive folder designated to hold messages of a particular class. You can set up a different receive folder for each message class that you handle or use one folder for all of the classes.

If you have registered for new mail notifications with the message store, you will be notified whenever a message is placed in a receive folder. If you have not registered for new mail notifications, you must open the appropriate receive folder periodically to manually check for the arrival of new messages.

Clients register for new mail notifications by setting the parameters to IMsgStore::Advise as follows:

• Set cbEntryID to 0.
• Set lpEntryID to NULL.
• Set ulEventMask to fnevNewMail.

The lpNotifications parameter in the call to your IMAPIAdviseSink::OnNotify method points to a NEWMAIL_NOTIFICATION structure that contains information about the incoming message, such as its message class, its entry identifier, the entry identifier of its parent folder, and the contents of its PR_MESSAGE_FLAGS property. For more information about registering for and handling notifications, see Handling Notifications.

Before displaying an incoming message to a user, determine if its message class is a class that your client supports. If not, ignore the message. If the class is one that you support, you can open and display the message with a form that is appropriate for the message class of the message. The choice of forms is based on message class. Messages that belong to the IPM class use a default form implemented by MAPI. Messages that belong to custom classes defined by clients can use either client-defined specialized forms or the MAPI default form.

To open and display an incoming message

1. Call IMsgStore::GetReceiveFolder to retrieve the entry identifier of the receive folder for the message class of the message and pass this entry identifier to IMsgStore::OpenEntry to open the folder. See Opening a Folder for more information.
2. Call the receive folder's IMAPIContainer::GetContentsTable method to retrieve its contents table. Call the table's IMAPITable::QueryRows method to retrieve all the rows in the table. For more information about contents tables in general, see Contents Tables. For more information about displaying a contents table, see Displaying a Folder Contents Table.
3. If your client is interactive, allow the user to select a message from the table and determine the form to be used to display that message. Clients can use the default form provided by MAPI or a custom form. For more information, see Handling MAPI Forms.
4. Call IMsgStore::OpenEntry to open the message. For more information, see Opening a Message.
5. Process the message text. See Opening Message Text.
6. Render each of the message attachments. See Rendering an Attachment in Plain Text or Rendering an Attachment in Formatted Text.
7. Open an attachment if desired. See Opening an Attachment.