AddressEntryFilter Object

AddressEntryFilter Object

The AddressEntryFilter object specifies criteria for restricting a search on an AddressEntries collection.

At a Glance

Properties

Methods

Remarks

An AddressEntryFilter object with no criteria is created by default for every AddressEntries 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 AddressEntries 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 AddressEntry object's property specified by the field's ID property.

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 address book container.

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 address entry filter affects traversals of the AddressEntries collection using the Visual Basic For Each statement, the Get methods, or the Visual Basic For ... Next construction. These accesses return an AddressEntry.

The AddressEntryFilter object is persistent within its parent AddressEntries collection. It is not deleted even when it is released, and it remains attached to the AddressEntries 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 an address entry filter of all of its previous settings and reset it to its default state of no criteria:

objAddrEntsColl.Filter = Nothing ' filter now invalidated and cleared
Set objAddrEntFilt = objAddrEntsColl.Filter ' new valid empty filter
 

If an address book container is being rendered with a CDO rendering application, the AddressEntries collection and the address entry filter are instantiated according to the specifications in the TableView object being applied to the address book container. The AddressEntryFilter 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 AddressEntries collection. This means that the collection is reinstantiated with a new address entry 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 address entry filter on a personal address book (PAB) should pass only AddressEntry objects that represent remote users OR that have a fax address:

Dim objThisPAB As AddressList           ' Personal address book
Dim objAddrEntFilt As AddressEntryFilter
Dim propTag As Long                     ' MAPI property tag
Dim dispType As Long                    ' MAPI display type

Set objThisPAB = objSession.AddressLists("Personal Address Book")
' ... validate AddressList object ...
Set objAddrEntFilt = objThisPAB.AddressEntries.Filter
' ... validate AddressEntryFilter object ...
dispTypeTag = &H39000003 ' VB4.0: dispTypeTag = CdoPR_DISPLAY_TYPE
dispTypeVal = 6          ' VB4.0: dispTypeVal = CdoRemoteUser
objAddrEntFilt.Fields.Add dispTypeTag, dispTypeVal
' case-insensitive substring match
objAddrEntFilt.Address = "fax:"
objAddrEntFilt.Or = True ' OR results together instead of AND