AddressEntryFilter Object
AddressEntryFilter Object
The AddressEntryFilter object specifies criteria for restricting a search on an AddressEntries collection.
At a Glance
Specified in type library: |
CDO.DLL |
First available in: |
CDO Library version 1.1 |
Parent objects: |
AddressEntries collection |
Child objects: |
Fields collection |
Default property: |
Properties
Name |
Available since version |
Type |
Access |
1.1 |
String |
Read/write |
|
1.1 |
String |
Read-only |
|
1.1 |
Long |
Read-only |
|
1.1 |
Field object or Fields collection object |
Read-only |
|
1.1 |
String |
Read/write |
|
1.1 |
Boolean |
Read/write |
|
1.1 |
Boolean |
Read/write |
|
1.1 |
AddressEntries collection object |
Read-only |
|
1.1 |
Session object |
Read-only |
Methods
Name |
Available since version |
Parameters |
1.1 |
objAddrEntryFilter2 as Object |
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