Fields Collection Object

Article
08/21/2009

Fields Collection Object

The Fields collection object contains one or more Field objects.

At a Glance

Specified in type library:	CDO.DLL
First available in:	CDO Library version 1.0.a
Parent objects:	AddressEntry AddressEntryFilter AddressList AppointmentItem Attachment Folder InfoStore MeetingItem Message MessageFilter
Child objects:	Field
Default property:	Item

A Fields collection is considered a small collection, which means that it supports count and index values that let you access an individual Field object through the Item property. The Fields collection supports the Microsoft® Visual Basic® For Each statement. For more information on collections, see Object Collections.

Properties

Name	Available since version	Type	Access
Application	1.0.a	String	Read-only
Class	1.0.a	Long	Read-only
Count	1.0.a	Long	Read-only
Item	1.0.a	Field object	Read-only
Parent	1.0.a	AddressEntry object, AddressEntryFilter object, AddressList object, AppointmentItem object, Attachment object, Folder object, InfoStore object, MeetingItem object, Message object, or MessageFilter object	Read-only
Session	1.0.a	Session object	Read-only

Methods

Name	Available since version	Parameters
Add	1.0.a	name as String, Class as Long, value as Variant, (optional) PropsetID as String, PropTag as Long
Delete	1.0.a	(none)
SetNamespace	1.0.a	PropsetID as String

Remarks

Field objects give you the ability to access MAPI properties on the parent object of the Fields collection. These include the predefined underlying MAPI properties and your own custom user-defined properties.

MAPI defines a set of properties with identifiers less than the value &H8000. These are known as unnamed properties because they are accessed using the MAPI property tag rather than a name. You can access these MAPI-defined properties using the Fields collection. All MAPI properties are accessible except those of types PT_OBJECT and PT_CLSID.

Data types are preserved between MAPI properties and CDO fields, with the exception of MAPI properties of type PT_BINARY. 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.

You can also extend the properties available through MAPI by defining your own properties. These user-defined properties, defined using a name and automatically assigned an identifier greater than &H8000 by CDO, are known as named properties. (C++ programmers can access the property name in the MAPI structure MAPINAMEID and convert it to the property tag value.)

All named properties are defined as part of a property set, which corresponds in the context of CDO to a name space.

A property set is defined by a GUID, or globally unique identifier. CDO represents this GUID as a string of hexadecimal characters. Such identifiers are usually referenced using a constant that starts with the characters PS_, such as PS_PUBLIC_STRINGS, the default property set for all properties created using the CDO Library.

You can also choose to organize your custom properties within their own name space by defining your own property set. The Add and Item properties and the SetNamespace method let you specify the property set identifier to be used for named property access.

When creating your own property set, you should be aware that MAPI reserves several property set identifiers for specific purposes. The following table lists reserved property sets:

Reserved property set	Description
PS_MAPI	Allows providers to supply names for the unnamed properties (properties with identifiers less than &H8000).
PS_PUBLIC_STRINGS	Default property set for custom properties added using CDO.
PS_ROUTING_ADDRTYPE	E-mail address types that are translated between messaging domains.
PS_ROUTING_DISPLAY_NAME	Display name properties that are translated between messaging domains.
PS_ROUTING_EMAIL_ADDRESSES	E-mail addresses that are translated between messaging domains.
PS_ROUTING_ENTRYID	Long-term entry identifiers that are translated between messaging domains.
PS_ROUTING_SEARCH_KEY	Search keys that are translated between messaging domains.

To create your own GUID that identifies your property set, you can either use the Win32® command-line utility UUIDGEN or you can call the OLE function CoCreateGuid to supply one for you, as demonstrated in the following code fragment:

' declarations required for the call to CoCreateGuid
Type GUID
    Guid1 As Long
    Guid2 As Long
    Guid3 As Long
    Guid4 As Long
End Type
Declare Function CoCreateGuid Lib "OLE32.DLL" (pGuid As GUID) As Long
Global Const S_OK = 0
Dim strPropID As String
Dim lResult As Long
Dim lGuid As GUID

' call CoCreateGuid, then convert the result to a hex string
    lResult = CoCreateGuid(lGuid)
    If lResult = S_OK Then
        strPropID =  Hex$(lGuid.Guid1) & Hex$(lGuid.Guid2)
        strPropID = strPropID & Hex$(lGuid.Guid3)
        strPropID = strPropID & Hex$(lGuid.Guid4)
    Else
        ' ... handle error ...
    End If

For more information on named properties and property sets, see "Named Properties" in the MAPI Programmer's Reference. For more information on UUIDGEN and CoCreateGuid, see "COM and ActiveX Object Services" in the Microsoft Platform SDK documentation.

MAPI stores all custom properties that represent date and time information using Greenwich Mean Time (GMT). CDO converts these properties so that the values appear to the user in local time.

Example

To uniquely identify a Field object in the Fields collection, use the Field object's Name or Index property, or the MAPI property tag:

Set objNamedField = objFolder.Fields.Item("BalanceDue")
Set objNamedField2 = objMessage.Fields.Item("Keyword")
Set objIndexedField = objMessage.Fields.Item(3)
propTag = &H0E180003 ' VB4.0: propTag = CdoPR_MESSAGE_DOWNLOAD_TIME
Set objMAPIField = objMessage.Fields.Item(propTag)

Fields Collection Object