Item Property (Fields Collection)
Item Property (Fields Collection)
The Item property returns a single Field object from the Fields collection. Read-only.
objFieldsColl.Item(name [, propsetID] )
Required. Specifies the Fields collection object.
Integer. Value must be greater than 0 and less than or equal to 65,535 (&HFFFF). Specifies the index within the Fields collection.
Long. Value must be greater than or equal to 65,536 (&H10000). Specifies the property tag value for the MAPI property to be retrieved.
String. Contains the custom name of the user-defined property, or a string representation of the of its property tag.
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.
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.
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.