Object Collections
Object Collections
A collection is a group of objects of the same type. In the CDO Library, the name of the collection takes the plural form of the individual CDO Library object. For example, the Messages collection is the name of the collection that contains Message objects. The CDO Library supports the following collections:
For purposes of accessing their individual member objects, collections can be characterized as either large or small.
For a small collection, the service provider maintains an accurate count of the objects in the collection. The AddressLists, Attachments, Fields, InfoStores, and Recipients collections are considered small collections. You can access individual items using an index into the collection. You can also add and delete items from the collection (except for the AddressLists and InfoStores collections, which are read-only for the CDO Library).
Small collections, with a known number of member objects, have a reliable Count property, which always contains the current number of member objects. The Item property can be used to select any arbitrary member of the collection. A small collection also has an implicit temporary Index property, assigned by the CDO Library. Index properties are valid only during the current MAPI session and can change as your application adds and deletes objects. The Index value for the first member object is 1.
For example, in an Attachments collection with three Attachment objects, the first attachment is referred to as Attachments.Item(1), the second as Attachments.Item(2), and the third as Attachments.Item(3). If your application deletes the second attachment, the third attachment becomes the second and Attachments.Item(3) has the value Nothing. The Count property is always equal to the highest Index in the collection.
Other applications can add and delete objects while your application is running. The Count property is not updated until you re-create or refresh the collection, for example by calling the parent Message object's Update or Send method. An attachment is saved in the MAPI system when you refresh the Message object, and the Count properties of its Attachments and Recipients collections are updated.
For a large collection, the service provider cannot always maintain an accurate count of the objects in the collection. The AddressEntries, Folders, and Messages collections are considered large collections. In preference to using a count, these collections support Get methods that let you get the first, last, next, or previous item in the collection. 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.
Large collections, with an uncertain number of member objects, support the Count property in a limited way. If the value of Count is set to CdoMaxCount, the provider is unable to furnish an accurate number of members, or even to indicate whether the collection is empty or not. If Count has a value other than CdoMaxCount, its value is reliable. The Item property has the same functionality as it does in small collections. For more information on using the Count and Item properties in a large collection, see the example in the Count property.
The Count property is updated whenever you refresh an AddressEntries or Messages collection, in particular by altering its child AddressEntryFilter or MessageFilter object.
MAPI assigns a permanent, unique string ID property when an individual member object is created. These identifiers do not change from one MAPI session to another. You can call the Session object's GetAddressEntry, GetFolder, or GetMessage method, specifying the unique identifier, to obtain the individual AddressEntry, Folder, or Message object. You can also use the GetFirst and GetNext methods to move from one object to the next in these collections.
Note To ensure correct operation of the GetFirst, GetLast, GetNext, and GetPrevious methods in a large collection, call GetFirst before making any calls to GetNext on that collection, and call GetLast before any calls to GetPrevious. To ensure that you are always making the calls on the same collection, create an explicit variable that refers to that collection.
For example, the following two code fragments are not equivalent:
' fragment 1: each Set statement creates a new Messages collection;
' it's undefined which message is returned by GetNext
Set objMessage = objInBox.Messages.GetFirst
...
Set objMessage = objInBox.Messages.GetNext
' fragment 2: use an explicit variable to refer to the collection;
' now the Get methods return the intended messages
Set objMsgColl = objSession.objInBox.Messages
Set objMessage = objMsgColl.GetFirst
...
Set objMessage = objMsgColl.GetNext
Code fragment 1 causes the CDO Library to create a new Messages collection in each Set statement. The GetFirst call returns the first message in the collection, but the result of the GetNext call is undefined since GetFirst has not yet been called on this new collection.
Code fragment 2 creates and uses the explicit variable objMsgColl, so the GetFirst and GetNext calls act as expected for collections with more than one item.
The collections in the CDO Library are specifically designed for messaging applications. The definition of collections in this document may differ slightly from the definitions of collections in the OLE programming documentation. Where there are differences, the description of the operation of the CDO Library supersedes the other documentation.