The ADSI search filters are used in two ways. They form a part of the LDAP dialect for submitting queries through the OLE DB provider. They are also used with the IDirectorySearch interface.

Operators

The following table lists frequently used search filter operators.

Logical operator

Description

=

Equal to

~=

Approximately equal to

<=

Lexicographically less than or equal to

>=

Lexicographically greater than or equal to

&

AND

|

OR

!

NOT

In addition to the operators above, LDAP defines two matching rule object identifiers (OIDs) that can be used to perform bitwise comparisons of numeric values. Matching rules have the following syntax.

<attribute name>:<matching rule OID>:=<value>

"" is the lDAPDisplayName of the attribute, "" is the OID for the matching rule, and "" is the value to use for comparison. Be aware that spaces cannot be used in this string. "" must be a decimal number; it cannot be a hexadecimal number or a constant name such as ADS_GROUP_TYPE_SECURITY_ENABLED. For more information about the available Active Directory attributes, see All Attributes.

The following table lists the matching rule OIDs implemented by LDAP.

Matching rule OID

String identifier (from Ntldap.h)

Description

1.2.840.113556.1.4.803

LDAP_MATCHING_RULE_BIT_AND

A match is found only if all bits from the attribute match the value. This rule is equivalent to a bitwise AND operator.

1.2.840.113556.1.4.804

LDAP_MATCHING_RULE_BIT_OR

A match is found if any bits from the attribute match the value. This rule is equivalent to a bitwise OR operator.

1.2.840.113556.1.4.1941

LDAP_MATCHING_RULE_IN_CHAIN

This rule is limited to filters that apply to the DN. This is a special "extended" match operator that walks the chain of ancestry in objects all the way to the root until it finds a match.

The following example query string searches for group objects that have the ADS_GROUP_TYPE_SECURITY_ENABLED flag set. Be aware that the decimal value of ADS_GROUP_TYPE_SECURITY_ENABLED (0x80000000 = 2147483648) is used for the comparison value.

The LDAP_MATCHING_RULE_IN_CHAIN is a matching rule OID that is designed to provide a method to look up the ancestry of an object. Many applications using AD and AD LDS usually work with hierarchical data, which is ordered by parent-child relationships. Previously, applications performed transitive group expansion to figure out group membership, which used too much network bandwidth; applications needed to make multiple roundtrips to figure out if an object fell "in the chain" if a link is traversed through to the end.

An example of such a query is one designed to check if a user "user1" is a member of group "group1". You would set the base to the user DN (cn=user1, cn=users, dc=x) and the scope to base, and use the following query.

(memberof:1.2.840.113556.1.4.1941:=cn=Group1,OU=groupsOU,DC=x)

Similarly, to find all the groups that "user1" is a member of, set the base to the groups container DN; for example (OU=groupsOU, dc=x) and the scope to subtree, and use the following filter.

(member:1.2.840.113556.1.4.1941:=cn=user1,cn=users,DC=x)

Note that when using LDAP_MATCHING_RULE_IN_CHAIN, scope is not limited—it can be base, one-level, or subtree. Some such queries on subtrees may be more processor intensive, such as chasing links with a high fan-out; that is, listing all the groups that a user is a member of. Inefficient searches will log appropriate event log messages, as with any other type of query.

Wildcards

You can also add wildcards and conditions to an LDAP search filter. The following examples show substrings that can be used to search the directory.

Get all entries:

(objectClass=*)

Get entries containing "bob" somewhere in the common name:

(cn=*bob*)

Get entries with a common name greater than or equal to "bob":

(cn>='bob')

Get all users with an email attribute:

(&(objectClass=user)(email=*))

Get all user entries with an email attribute and a surname equal to "smith":

(&(sn=smith)(objectClass=user)(email=*))

Get all user entries with a common name that starts with "andy", "steve", or "margaret":

(&(objectClass=user)(| (cn=andy*)(cn=steve*)(cn=margaret*)))

Get all entries without an email attribute:

(!(email=*))

The formal definition of the search filter is as follows (from RFC 1960):

The token is a string that represents an AttributeType. The token is a string that represents an AttributeValue whose format is defined by the underlying directory service.

If a must contain the asterisk (*), left parenthesis ((), or right parenthesis ()) character, the character should be preceded by the backslash escape character ().

Special Characters

If any of the following special characters must appear in the search filter as literals, they must be replaced by the listed escape sequence.

ASCII character

Escape sequence substitute

*

\2a

(

\28

)

\29

\

\5c

NUL

\00

/

\2f

Note

In cases where a MultiByte Character Set is being used, the escape sequences listed above must be used if the search is performed by ADO with the SQL dialect.

In addition, arbitrary binary data may be represented by using the escape sequence syntax by encoding each byte of binary data with the backslash () followed by two hexadecimal digits. For example, the four-byte value 0x00000004 is encoded as \00\00\00\04 in a filter string.