CDO & MAPI Programming with Visual Basic:

The MAPIMessages Control

The MAPIMessages control is used to manipulate messages. After signing on to MAPI using the MAPISession control, you must set the SessionID property of the MAPIMessages control equal to the SessionID property of the MAPISession control, like this:

MAPIMessages1.SessionID = MAPISession1.SessionID

After doing so, you can compose and manipulate messages until you call the SignOff method of the MAPISession control.

Tip

The MAPI controls access only a user’s Inbox. No other folders are available, not even other message folders such as Sent Items or Deleted Items, nor any nested folders that have been created inside or nested within the Inbox.

Structure of the MAPIMessages Control

The MAPIMessages control has properties related directly to messages (e.g., MsgSubject, MsgNoteText), properties related to attachments (e.g., AttachmentName, AttachmentType), and properties related to recipients (e.g., RecipDisplayName, RecipType). These three categories are important because each property in each group actually references an array of values. The mechanism for accessing these values is similar in all three cases.

Consider the message-related properties. It’s clear that an Inbox may have more than one message. When reading the MsgNoteText property, for example, there must be a way to tell the control which message to access. The MsgIndex property has been provided for this purpose. All of the properties that reference messages retrieve their values from the message that is indicated by the current value of MsgIndex. This is referred to as the currently indexed message. The total number of messages is given by the MsgCount property. MsgIndex is zero-based, so its value can range from through (MsgCount - 1). It is an error to set the MsgIndex property to a value higher than MsgCount - 1. To give an example, the following code loops through all messages, adding each message’s subject line to a list box named lstSubjects (the Fetch method will be discussed later):

Dim nMsgIndex As Long

lstSubjects.Clear
MAPIMessages1.Fetch
For nMsgIndex = 0 To MAPIMessages1.MsgCount - 1
   MAPIMessages1.MsgIndex = nMsgIndex ' set the current message
   lstSubjects.AddItem MAPIMessages1.MsgSubject
   lstSubjects.ItemData(lstSubjects.NewIndex) = nMsgIndex
Next nMsgIndex

Similarly, attachment-related properties are relative to the currently indexed attachment, as specified in the AttachmentIndex property. The number of attachments is given by the AttachmentCount property. Recipient-related fields are relative to the RecipIndex property, with the number of recipients given by the RecipCount property. Note that AttachmentIndex and RecipIndex, like MsgIndex, are zero-based. Note also that attachments and recipients are relative not only to AttachmentIndex and RecipIndex, respectively, but also to the currently indexed message. (In other words, attachments and recipients are accessed using a two-dimensional array, whereas messages are accessed using a one-dimensional array.) Therefore, to refer to a specific attachment, for example, first set the MsgIndex property to select the desired message, then set the AttachmentIndex property to select a specific attachment on that message. Given a message index nMsg, and an attachment index nAttachment, this code retrieves the given attachment’s display name:

MAPIMessages1.MsgIndex = nMsg
MAPIMessages1.AttachmentIndex = nAttachment
strName = MAPIMessages1.AttachmentName

Example 4-1 further demonstrates the use of these indices by displaying (in Visual Basic’s Immediate window) summary information for all messages, recipients, and attachments fetched by the MAPIMessages control.

Example 4-1. Looping Through Messages, Recipients, and Attachments

Private Sub DebugPrintMessagesRecipientsAttachments( )

   ' Demonstrate the MsgIndex, RecipIndex, and AttachmentIndex
   ' properties by looping through all messages, all recipients,
   ' and all attachments, printing information about each to the
   ' debug window.
   
   ' Loop control variables.
   Dim nMsg As Long
   Dim nRecip As Long
   Dim nAttachment As Long
   
   ' Sign on.
   With MAPISession1
      .DownLoadMail = False
      .LogonUI = True
      .NewSession = True
      .Password = ""
      .UserName = "MyProfile"
      .SignOn
   End With
   
   ' Associate MAPIMessages control with current session.
   MAPIMessages1.SessionID = MAPISession1.SessionID
   
   ' Fetch messages.
   MAPIMessages1.Fetch
   
   ' This outer loop cycles through all messages.
   For nMsg = 0 To MAPIMessages1.MsgCount - 1
   
      ' Set the control's message index. Subsequent access to the
      ' control's properties will reference this specific message.
      MAPIMessages1.MsgIndex = nMsg
   
      ' Print info about this message.
      Debug.Print "Message #"; Trim(CStr(nMsg)); ": "; _
         MAPIMessages1.MsgSubject
      
      ' Now show all recipients for this specific message.
      For nRecip = 0 To MAPIMessages1.RecipCount - 1
      
         ' Set the control's recipient index. Subsequent access to
         ' the control's properties will reference this specific
         ' recipient on the currently indexed message (the one
         ' specificed by .MsgIndex).
         MAPIMessages1.RecipIndex = nRecip
         
         ' Print info about this recipient. Indent the info to show
         ' its relationship to the message info printed earlier.
         Debug.Print "   Recipient #"; Trim(CStr(nRecip)); ": "; _
            MAPIMessages1.RecipDisplayName
            
      Next nRecip
      
      ' Now show all attachments for this specific message.
      For nAttachment = 0 To MAPIMessages1.AttachmentCount - 1
      
         ' Set the control's attachment index. Subsequent access to
         ' the control's properties will reference this specific
         ' attachment on the currently indexed message (the one
         ' specified by .MsgIndex).
         MAPIMessages1.AttachmentIndex = nAttachment
         
         ' Print info about this attachment. Indent the info to show
         ' its relationship to the message info printed earlier.
         Debug.Print "   Attachment #"; Trim(CStr(nAttachment)); _
            ": "; MAPIMessages1.AttachmentName
            
      Next nAttachment
      
   Next nMsg
   
   ' All done. Sign off.
   MAPISession1.SignOff



End Sub ' DebugPrintMessagesRecipientsAttachments