Handling Attachments with Simple MAPI

Simple MAPI handles attachments by means of an array of MapiFileDesc structures pointed to by the lpFiles member of a MapiMessage structure. The nFileCount member of the MapiMessage structure indicates the length of the array, with a value of 0 indicating there are no attachments. All Simple MAPI attachments are returned by means of temporary files.

Simple MAPI recognizes three types of attachments: data files, editable OLE objects, and static OLE objects. Use the values of the flFlags and lpszFileName members of a MapiFileDesc structure to determine the type of attachment it describes. OLE 2 attachments are identified by the .STG extension in the lpszFileName member. OLE 1 attachments are identified by the MAPI_OLE flag in the flFlags member. OLE 1 compliant clients which receive OLE 2 attachments can convert them by handling the OLE IStorage interface themselves or by using an OLE server to convert them to OLE 1. Embedded messages are data files that have the .MSG extension in the lpszFileName member.

Each attachment has an nPosition member that stores its position within the message. The position is an index into the message's lpszNoteText member — which can be treated as an array of characters. The attachment will appear at the character at its position in the message; that is, the attachment will be rendered instead of the character lpszNoteText[nPosition]. The special value -1 (0xFFFFFFFF) indicates that the attachment is not rendered in this way; in this case, the client receiving the message is responsible for providing the user with a way of accessing the attachment. Note that the position is a character position within the text note, not a byte offset into the text note. This is an important distinction when double byte character sets are in use.

Note  The attachment should be rendered instead of the character stored in lpszNoteText[nPosition]. The actual value of lpszNoteText[nPosition] should be completely immaterial to the way the message is displayed to the user.

To add attachments to a message

1. Allocate an array of MapiFileDesc structures, one for each attachment.
2. Set the members of each array element to values appropriate for the data files or OLE objects that are being attached.
3. Set the message's nFileCount member to the number of attachments.
4. Set the message's lpFiles member to the address of the first element of the array of MapiFileDesc structures.

To handle attachments in a message your client has received

1. Scan the attachments in the array of MapiFileDesc structures and note their character positions.
2. When displaying the message text for the user, place graphic representations of data file attachments or OLE objects at the appropriate positions.
3. Provide a mechanism for the user to interact with the attachments. You might choose to implement a point-and-click interface, or allow users to select actions such as saving and opening from a menu.