Item Property (Fields Collection)
Item Property (Fields Collection)
The Item property returns a single Field object from the Fields collection. Read-only.
Syntax
objFieldsColl.Item(index)
objFieldsColl.Item(proptag)
objFieldsColl.Item(name [, propsetID] )
objFieldsColl
Required. Specifies the Fields collection object.
index
Integer. Value must be greater than 0 and less than or equal to 65,535 (&HFFFF). Specifies the index within the Fields collection.
proptag
Long. Value must be greater than or equal to 65,536 (&H10000). Specifies the property tag value for the MAPI property to be retrieved.
name
String. Contains the custom name of the user-defined property, or a string representation of the of its property tag.
propsetID
Optional. String. Contains the GUID that identifies the property set, represented as a string of hexadecimal characters. When propsetID is not supplied, the property set used for the access is the default property set value most recently set by this collection's SetNamespace method, or the initial default property set value, PS_PUBLIC_STRINGS.
The Item property is the default property of a Fields collection, meaning that objFieldsColl**(index)** is syntactically equivalent to objFieldsColl.Item(index) in Microsoft® Visual Basic® code.
Data Type
Object (Field)
Remarks
The Item property works like an accessor property for small collections. In the Fields collection object it allows access to the predefined MAPI properties and to your own custom user-defined properties.
The proptag parameter in the second syntax contains the 32-bit MAPI property tag associated with the property and corresponds to the ID property of the Field object. The property tag contains the MAPI property identifier in its high-order 16 bits and the MAPI property type in its low-order 16 bits. All MAPI properties are accessible except those of MAPI type PT_OBJECT or PT_CLSID.
Note that not all MAPI property types can be manipulated within CDO. In particular, the MAPI types PT_ERROR, PT_I8, PT_LONGLONG, and PT_SYSTIME do not have corresponding CDO data types. Properties of these types can be obtained with the Item property but cannot be assigned, altered, or compared within CDO. They can, however, be rendered by the ContainerRenderer object's RenderProperty method or the ObjectRenderer object's RenderProperty method.
The name parameter in the third syntax must be a string. It contains either the custom property's name or its property tag. The tag must be represented as an ASCII string, which must consist of the characters "0x" followed by up to eight hexadecimal digits. Combined with the GUID in the propsetID parameter, this syntax allows you to access properties from a property set other than your default set, either by name or by property tag.
If you have a custom property name that starts with the string "0x" you cannot access it with the name parameter, because the third syntax attempts to interpret the characters following "0x" as hexadecimal digits.
If the specified property is not present in the Fields collection, the Item property returns CdoE_NOT_FOUND.
Several macros for C/C++ programmers are available in the MAPI Programmer's Reference to help manipulate the MAPI property tag data structure. The macros PROP_TYPE and PROP_ID extract the property type and property identifer from the property tag. The macro PROP_TAG builds the property tag from the type and identifier components.
Although the Item property itself is read-only, the Field object it returns can be accessed in the normal manner, and its properties retain their respective read/write or read-only accessibility.
Example
This code fragment accesses a custom user-defined property using its property name:
' from the function Fields_ItemByName()
' error handling here ...
If objFieldsColl Is Nothing Then
MsgBox "Must first select Fields collection"
Exit Function
End If
Set objOneField = objFieldsColl.Item("Keyword")
' could be objFieldsColl("Keyword") since .Item is default property
If objOneField Is Nothing Then
MsgBox "could not select Field object"
Exit Function
End If
If "" = objOneField.Name Then
MsgBox "Keyword has no name; ID = " & objOneField.ID
Else
MsgBox "Keyword name = " & objOneField.Name
End If
You can also use the Item property to access MAPI properties. The defined MAPI properties are unnamed properties and can only be accessed using the numeric proptag value. They cannot be accessed using a string that represents the name. This code fragment accesses the MAPI property PR_MESSAGE_CLASS:
' from the function Fields_Selector()
' ... error handling here
' you can provide a dialog to allow entry for MAPI proptags
' or select property names from a list; for now, hard-coded
lValue = CdoPR_MESSAGE_CLASS ' = &H001A001E
' high-order 16 bits are property ID; low-order are property type
Set objOneField = objFieldsColl.Item(lValue)
If objOneField Is Nothing Then
MsgBox "Could not get the Field using the value " & lValue
Exit Function
Else
strMsg = "Used " & lValue _
& " to access the MAPI property " _
& "PR_MESSAGE_CLASS: type = " _
& objOneField.Type _
& "; value = " _
& objOneField.Value
MsgBox strMsg
End If
CDO also supports multivalued MAPI properties.
You can also choose to access properties from other property sets, including your own, by either setting the propsetID parameter or by calling the SetNamespace method to set that property set's unique identifier.
For more information on working with MAPI properties, see Customizing a Folder or Message and Viewing MAPI Properties.