Item Property (Messages Collection)

The Item property returns a single AppointmentItem, GroupHeader, MeetingItem, or Message object from the Messages collection. Read-only.

Syntax

objMsgColl.Item(index)

objMsgColl.Item(searchValue)

index

A long integer ranging from 1 to the size of the Messages collection.

searchValue

A string used to search the Messages collection starting at the current position. The search returns the next Message object having the current sorting property greater than or equal to the searchValue string.

The Item property is the default property of a Messages collection, meaning that objMsgColl(index) is syntactically equivalent to objMsgColl.Item(index) in Microsoft® Visual Basic® code.

Data Type

Object (GroupHeader or Message)

Remarks

Programmers needing to access individual objects in a large collection are strongly advised to use the Visual Basic For Each statement or the Get methods, particularly GetFirst and GetNext.

The Item(index) syntax returns the AppointmentItem, GroupHeader, MeetingItem, or Message object at the indicated position in the collection. It can be used in an indexed loop, such as the For ... Next construction in Visual Basic. The first item in the collection has an index of 1.

If you are accessing a Messages collection instantiated by a CDO rendering application, the collection may come from a calendar folder, or there may be a grouped view applied to the folder. Therefore you can get AppointmentItem, GroupHeader, and MeetingItem objects returned as well as Message objects. Because of this, you should declare the Visual Basic variable being set to the Item property to be an Object rather than a Message, and you should also test the Class property of each returned object to see if it is an appointment, group header, meeting, or message:

  Dim objMember As Object ' could get one of several classes 
  ' collMessages is instantiated from a rendering application 
  ' assume collMessages valid 
  ' ... 
  For Each objMember in collMessages ' collection from a rendering 
    If objMember.Class = CdoMsg ' exclude other classes 
      ' we have a Message object 
    End If 
  Next 
 

For more information on using the Count and Item properties in a large collection, see the example in the Count property.

The Item(searchValue) syntax returns the next Message object whose current sorting property is greater than or equal to the string specified by searchValue. This syntax only applies when the Messages collection contains Message objects.

The searchValue syntax starts its search at the current position and retrieves only messages and not group headers. Searching is based on the current sort order of the collection. The default sort property for a Messages collection is the TimeReceived property of the collection’s Message objects. If you want to use the Item(searchValue) syntax to search the collection on another property, for example a message subject, you should first call the Sort method specifying the Subject property.

Note  The Item(searchValue) syntax uses the IMAPITABLE::FindRow method, which performs a search dependent on the current sort order of the table underlying the collection. Not all tables are sorted alphabetically. If your most recent sort order is nonalphabetic, you should access the messages using the Item(index) syntax. This applies, for example, to messages in Microsoft Exchange Public Folders, which are held in an order determined by the currently applied view.

For more information on tables, bookmarks, restrictions, and sort and search orders, see the MAPI Programmer’s Reference.

Although the Item property itself is read-only, the AppointmentItem, GroupHeader, MeetingItem, or Message object it returns can be accessed in the normal manner, and its properties retain their respective read/write or read-only accessibility.