CDOLive LLC The Premier Resource for Microsoft Collaboration Data Objects             

Object Model

CDO 1.21 has an object model for the standard CDO library and the CDO HTML rendering library, which is completely independent from the Microsoft Outlook object model. However, you can use CDO 1.21 in your application, including Microsoft Outlook, to build powerful Workflow and Groupware solutions.

Click to view the description

CDO 1.21 Objects and Collections Description

This list of CDO 1.21 Objects and Collections is compiled from the CDO.HLP file which is included on the Microsoft Exchange Server 5.5 CD-ROM. Note that an updated CDO.HLP file is included in the Microsoft Exchange Server 5.5 Service Pack 1 (or higher). You can also download the most current version from CDOLive cdo.zip (1,065 Kbyte).

Object Description
Session (Object only) The Session object contains session-wide settings and options. It also contains properties that return top-level objects, such as CurrentUser. A Session object is considered a top-level object, meaning it can be created directly from a Microsoft Visual Basic program. In the CDO for Exchange Library it has a ProgID of MAPI.Session.
Note that you specify the full ProgID "MAPI.Session" instead of just "Session" in order to distinguish a MAPI session from other types of sessions available to a Visual Basic Script program through other object libraries.

After you create a new Session object, you use the Logon method to initiate a session with MAPI. No other activities with CDO are permitted prior to a successful logon.

You can use anonymous or authenticated logon to access Exchange Information.

Anonymous access can only be used to access public folders, for example to display the content of a public folder in an Intranet or Internet Web site. With anonymous access no logon information is required and no dialog box for a logon is displayed.

With authenticated access users are authenticated against a Windows NT account. Authenticated access can be used to access public folders and private folders.
InfoStores (Object and Collection) The InfoStore object provides access to the folder hierarchy through the RootFolder property. You can obtain any InfoStore object available to this session with the Item property of the InfoStores collection. You can also retrieve an InfoStore object with a known identifier by calling the session's GetInfoStore method.

The InfoStores collection object contains one or more InfoStore objects. The InfoStores collection provides access to all InfoStore objects available to this session. Each InfoStore object in turn offers access to the folder hierarchy of that message store. This is used primarily to obtain access to public and private folders.

CDO does not support methods to add or remove InfoStore objects from the collection.

In general, you cannot assume that the InfoStore object's name property is unique. This means that you cannot rely on the name to retrieve the InfoStore from the collection. However, you can iterate through all objects in the collection using the InfoStores collection object's Item property, and then examine properties of the individual InfoStore objects. You can also rely on the InfoStore object's ID property, which is guaranteed to be unique.
RootFolder (Object only) The RootFolder property returns a folder object representing the root of the IPM subtree for the InfoStore object.
The InfoStore object provides access to its interpersonal message folder hierarchy through the RootFolder property, which returns the folder object that represents the root of the IPM subtree. To access the root folder of the entire message store, first obtain its identifier with the FolderID property of the IPM root folder, and then call the session object's GetFolder method.

You can obtain any InfoStore object available to this session with the item property of the InfoStores collection. You can also retrieve an InfoStore object with a known identifier by calling the session's GetInfoStore method.
Messages (Object and Collection) Developers can create new Message objects using the Messages collection's Add method.

A message can be obtained from its parent Messages collection using the collection's Item property. To get to the Messages collection in a folder, use the Folder object's Messages property. If you know a message's unique identifier, you can obtain it directly from the Session object's GetMessage method.
Attachments (Object and Collection) An attachment is an object, such as a file or an OLE object, that is associated with and transmitted with a Message object. It is assigned a particular location within the message, specified by the Position property, and overwrites the character at that position when the message is displayed to a messaging user. Typically, a placeholder such as an icon is displayed instead of the attachment's contents, until the user requests that the attachment be opened and displayed in its entirety.

CDO does not manage the actual display of the attachment or its placeholder. The properties of the Attachment object simply provide information which the displaying application can use to find and open the attachment, select a suitable placeholder, and convert the attachment's contents into a display.
Fields (Object and Collection) The Field object gives you the ability to access MAPI properties on an AddressEntry, AddressEntryFilter, AddressList, Recipients, Attachment, Folder, InfoStore, RootFolder, Message, or MessageFilter object. The properties can be predefined MAPI properties or custom named properties.

You do not have to add a predefined property to the Fields collection in order to access it. You can set it or read its value by simply supplying its property tag to the collection's Item property. To access a custom property, you normally have to use the Fields collection's Add method to establish access to the property.

You can add additional properties tailored for your specific application to the Fields collection. Before adding a field for an object, review the properties that are already provided by CDO. Many of the most common ones are already offered. For example, Subject and Importance are already defined as Message object properties.

Data types are preserved between MAPI properties and CDO fields, with the exception of binary type MAPI properties. These are converted from counted binary in MAPI to character string representation in CDO, where the characters in the string represent the hexadecimal digits of the MAPI property value. The string is converted back into counted binary when you write to the field.

Note that the predefined MAPI properties are unnamed when they are accessed through Field objects. For these MAPI properties, the Name property is an empty string. A list of all MAPI properties can be found at the MSDN Library  (Please look at the topic Digging deeper into CDO, Useful Links) or the CDO.HLP file.
Recipients (Object and Collection) The Recipient object represents one recipient of a message. The Recipients collection object contains one or more Recipient objects and specifies the recipients of a message.

A Recipients collection is a collection which supports count and index values that let you access an individual Recipient object through the Item property. The Recipients collection supports the Microsoft Visual Basic For Each statement.
MessageFilter (Object only) The MessageFilter object specifies criteria for restricting a search on a Messages collection.

A MessageFilter object with no criteria is created by default for every Messages collection. This means that initially the filter's properties are unset and its child Fields collection is empty. You specify the filter by setting values for its properties or adding fields to its Fields collection. You do not need to call any Update method when setting filter criteria.

The filter is invoked when the Messages collection is traversed with the Get methods or the Microsoft Visual Basic For Each construction. Each field participates in a MAPI search restriction comparing the field's Value property against the value of the Message object's property specified by the field's ID property.

If the underlying messaging system does not support the search criteria specified by the filter fields, the Get methods return CdoE_TOO_COMPLEX. In particular, a given field may not be supported by a particular message store. You can apply a MessageFilter object to a Messages collection containing AppointmentItem objects. However, the current version of CDO only supports filtering on the appointment's EndTime and StartTime properties. An attempt to filter on any other properties, including the inherited Message object properties, returns CdoE_TOO_COMPLEX. The current version of CDO also does not support any of the MessageFilter's properties other than the Fields property when the filter is applied to a collection of appointments.
Folders (Object and Collection) The Folder object represents a folder or container within the MAPI system. A folder can contain subfolders and messages.

The Folders collection object contains one or more Folder objects. A Folders collection is considered a large collection, which means that the Count property has limited validity, and the best way to access an individual Folder object within the collection is to use either its unique identifier or the Get methods.

Large collections, such as the Folders collection, cannot always maintain an accurate count of the number of objects in the collection. It is strongly recommended that you use the GetFirst, GetLast, GetNext, and GetPrevious methods to access individual items in the collection. You can access one specific folder by using the Session object's GetFolder method, and you can access all the items in the collection with the Microsoft Visual Basic For Each construction.

The order that items are returned by GetFirst, GetLast, GetNext, and GetPrevious depends on whether the folders are sorted or not. The Folder objects within a collection can be sorted on a MAPI property of your choice, either ascending or descending, using the Sort method. When the items are not sorted, you should not rely on these methods to return the items in any specified order. The best programming approach to use with unsorted collections is to assume that the access functions are able to access all items within the collection, but that the order of the objects is not defined.
AddressLists (Object and Collection) The AddressList object supplies a list of address entries to which a messaging system can deliver messages. An AddressList object represents one address book container available under the MAPI address book hierarchy for the current session.

The AddressLists collection object contains one or more AddressList objects. An AddressLists collection is a small collection, which supports count and index values that let you access an individual AddressList object through the Item property. The AddressLists collection supports the Microsoft Visual Basic For Each statement.

The AddressLists collection provides access to the root of the MAPI address book hierarchy for the current session. You can obtain the collection through the parent Session object's AddressLists property.

You can use the Count and Item properties to traverse the hierarchy for all available address books, or you can use the Item property to select a particular AddressList object. The type of access you obtain depends on the access granted to you by each available address book provider.
AddressEntries (Object and Collection) The AddressEntry object defines addressing information valid for a given messaging system. An address usually represents a person or process to which the messaging system can deliver messages.

The AddressEntries collection object contains one or more AddressEntry objects. An AddressEntries collection is considered a large collection, which means that the Count property has limited validity, and the best way to access an individual AddressEntry object within the collection is to use either its unique identifier or the Get methods.

Each AddressEntry object in the collection holds information representing a person or process to which the messaging system can deliver messages. An AddressEntries collection provides access to the entries in a MAPI address book container.

Large collections, such as the AddressEntries collection, cannot always maintain an accurate count of the number of objects in the collection. It is strongly recommended that you use the GetFirst, GetLast, GetNext, and GetPrevious methods to access individual items in the collection. You can access one specific address entry by using the Session object's GetAddressEntry method, and you can access all the items in the collection with the Microsoft Visual Basic For Each construction.

The order that items are returned by GetFirst, GetLast, GetNext, and GetPrevious depends on whether the address entries are sorted or not. The AddressEntry objects within a collection can be sorted on a MAPI property of your choice, either ascending or descending, using the Sort method. When the items are not sorted, you should not rely on these methods to return the items in any specified order. The best programming approach to use with unsorted collections is to assume that the access functions are able to access all items within the collection, but that the order of the objects is not defined.
AddressEntryFilter (Object only) The AddressEntryFilter object specifies criteria for restricting a search on an AddressEntries collection.
An AddressEntryFilter object with no criteria is created by default for every AddressEntries collection. This means that initially the filter's properties are unset and its child Fields collection is empty. You specify the filter by setting values for its properties or adding fields to its Fields collection. You do not need to call any Update method when setting filter criteria.

The filter is invoked when the AddressEntries collection is traversed with the Get methods or the Microsoft Visual Basic For Each construction. Each field participates in a MAPI search restriction comparing the field's Value property against the value of the AddressEntry object's property specified by the field's ID property.

If the underlying messaging system does not support the search criteria specified by the filter fields, the Get methods return CdoE_TOO_COMPLEX. In particular, a given field may not be supported by a particular address book container. The results of the individual restrictions are normally ANDed together to form the final filter value. You can change this by setting the Or property, which causes all the results to be ORed instead of ANDed. You can also set the Not property to specify that the result of each individual restriction is to be negated before being ANDed or ORed into the final filter value.

The address entry filter affects traversals of the AddressEntries collection using the Visual Basic For Each statement, the Get methods, or the Visual Basic For ... Next construction. These accesses return an AddressEntry.