MessageFilter Object

MessageFilter Object

The MessageFilter object specifies criteria for restricting a search on a Messages collection.

At a Glance

Properties

Methods

Remarks

A MessageFilter object with no criteria is created by default for every Messages collection. This means that initially the filter’s properties are unset and its child Fields collection is empty. You specify the filter by setting values for its properties or adding fields to its Fields collection. You do not need to call any Update method when setting filter criteria.

The filter is invoked when the Messages collection is traversed with the Get methods or the Microsoft® Visual Basic® For Each construction. Each field participates in a MAPI search restriction comparing the field’s Value property against the value of the Message object’s property specified by the field’s ID property.

When you are traversing a Messages collection instantiated by a CDO rendering application, you should declare the Visual Basic variable to be an Object instead of a Message. This is because the collection may be from a calendar folder, and also because a rendering may have applied a grouped view to the folder. Therefore you can get AppointmentItem, GroupHeader, and MeetingItem objects returned as well as Message objects. You should also test the Class property of each returned object to see if it is an appointment, a group header, a meeting, or a message:

  Dim objMember As Object ' could get one of several classes
  ' collMessages is instantiated from a rendering application
  ' assume collMessages valid
  ' ...
  For Each objMember in collMessages ' collection from a rendering
    If objMember.Class = CdoMsg ' exclude other classes
      ' we have a Message object
    End If
  Next
 

For fields of data type other than String, the MAPI search restriction type is RES_PROPERTY with relational operator RELOP_EQ. For fields of data type String, the restriction type is RES_CONTENT with fuzzy level options FL_SUBSTRING, FL_IGNORECASE, and FL_LOOSE. However, the following MAPI properties are compared using FL_PREFIX instead of FL_SUBSTRING:

PR_ACCOUNT

PR_BUSINESS_ADDRESS_CITY

PR_COMPANY_NAME

PR_DEPARTMENT_NAME

PR_DISPLAY_NAME

PR_GIVEN_NAME

PR_OFFICE_LOCATION

PR_SURNAME

PR_TITLE

If the underlying messaging system does not support the search criteria specified by the filter fields, the Get methods return CdoE_TOO_COMPLEX. In particular, a given field may not be supported by a particular message store.

You can apply a MessageFilter object to a Messages collection containing AppointmentItem objects. However, the current version of CDO only supports filtering on the appointment's EndTime and StartTime properties. An attempt to filter on any other properties, including the inherited Message object properties, returns CdoE_TOO_COMPLEX. The current version of CDO also does not support any of the MessageFilter's properties other than the Fields property when the filter is applied to a collection of appointments.

MeetingItem objects are members of a Messages collection belonging to a messaging user's Inbox, and they can be filtered on any properties, including the inherited Message object properties.

The MAPI search restrictions for appointment properties are as follows:

The comparison order is (property value)(relational operator)(constant value). For example, the message filter passes appointments with a starting date earlier than or equal to the date you indicate. To specify this restriction, you use the filter's Fields property to obtain its Fields collection, Add a new Field with CdoPR_START_DATE in the PropTag parameter, and set the new field's Value property to the last admissible starting date.

The results of the individual restrictions are normally ANDed together to form the final filter value. You can change this by setting the Or property, which causes all the results to be ORed instead of ANDed. You can also set the Not property to specify that the result of each individual restriction is to be negated before being ANDed or ORed into the final filter value.

The message filter affects traversals of the Messages collection using the Visual Basic For Each statement, the Get methods, or the Visual Basic For ... Next construction. These accesses normally return a Message object but can also return a GroupHeader object if the collection is instantiated by a CDO rendering application.

The MessageFilter object is persistent within its parent Messages collection. It is not deleted even when it is released, and it remains attached to the Messages collection until the collection’s Filter property is set to Nothing or the collection is itself released. You can use the following code to clear a message filter of all of its previous settings and reset it to its default state of no criteria:

objMessagesColl.Filter = Nothing ' filter now invalidated and cleared
Set objMessageFilt = objMessagesColl.Filter ' new valid empty filter
 

If a folder is being rendered with a CDO rendering application, the Messages collection and the message filter are instantiated according to the specifications in the TableView object being applied to the folder. The MessageFilter object inherits the restriction specified in the view. An inherited filter can be used without modification, but it cannot be read or changed by the rendering application. Writing any property on an inherited filter disinherits it and refreshes the Messages collection. This means that the collection is reinstantiated with a new message filter specifying only the property just written. This new filter, however, is no longer inherited, and the application can read its properties and set additional restrictions within it.

Example

This code fragment specifies that the message filter on the Inbox should pass only Message objects that are Not of message class IPM.Note AND are Unread:

Dim objMsgFilt As MessageFilter
  ...
Set objMsgFilt = objSession.Inbox.Messages.Filter
' ... validate MessageFilter object ...
objMsgFilt.Not = True ' negate all results before ANDing
objMsgFilt.Type = "IPM.Note" ' MAPI message class
objMsgFilt.Unread = False ' .Not setting negates True to False!