Field Object

A Field object represents a MAPI property on a Microsoft® CDO Library object.

At a Glance

Properties

Methods

Remarks

The Field object gives you the ability to access MAPI properties on an AddressEntry, AddressEntryFilter, AddressList, AppointmentItem, Attachment, Folder, InfoStore, MeetingItem, 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 eligible 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 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.

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.

The Field object also supports multivalued MAPI properties. The multivalued property appears to the Microsoft® Visual Basic® application as a vbVariant array. When you write to a multivalued field, it accepts arrays of various data types, such as vbLong and vbString. When you read from a multivalued field, however, it always returns a vbVariant array. You can use the For ... Next statement to access individual array entries, as shown in this code fragment:

   Dim rgstr(0 To 9) As String ' field accepts a string array 
   ' Build array of values for multivalued property 
   For i = 0 To 9 
      rgstr(i) = "String" + Str(i) 
   Next 
 
   ' Create MV field on the message (note that we don't specify 
   ' the array as third argument to Fields.Add, but add separately) 
   Set f = msg.Fields.Add("FancyName", vbString + vbArray) 
   f.Value = rgstr ' Set value of new field; accepts a string array 
   ' Save/send the message, logoff, etc. 
 
   ' later: code that reads the multivalued properties 
   Dim rgret (0 To 9) As Variant ' field returns a variant array 
   Set f = msg.Fields.Item("FancyName") ' Get multivalued Field 
   rgret = f.Value ' Get array of values into a variant array 
   For i = LBound(rgret) To UBound(rgret) 
      MsgBox rgret(i) 
   Next i 
 

For more information on multivalued fields, see the Field object's Type property.

For more information on MAPI properties, see the reference documentation for the Fields collection and the MAPI Programmer's Reference.