Fields Collection Object

The Fields collection object contains one or more Field objects.

At a Glance

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

Methods

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:

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)