| Platform SDK: Active Directory, ADSI, and Directory Services |
You can specify that your query be restricted to the following limits: a base query, a one-level query, or a subtree search.
A base query limits the search to only the base object. The maximum number of objects returned is always one. This search is useful to verify the existence of an object. For example, if you have an object's distinguished name and you need to verify the object's existence based on the path, you can use a one-level search. If the search fails, you can assume that the object may have been renamed or moved to a different location, or that you were given the wrong information about the object. (Note that you should store the GUID instead of the distinguished name if you wish to revisit an object. This allows the object to be renamed or moved in the directory hierarchy without breaking the persisted link.)
A one-level search is restricted to the immediate children of a base object, but excludes the base object itself. This setting can perform a targeted search for immediate child attributes of a parent object. For example, if you have a parent object called P1, and its immediate children are: C1, C2, C3, then in a one-level search, C1, C2, and C3 should be included when evaluating the criteria, but P1 would not be part of the search. A one-level search can be used to enumerate all children of an object. In fact, in some ADSI providers, IADsContainer enumeration translates to a one-level search.
A subtree search (or a deep search) includes all the objects excluding the base object. This search may generate referrals to other servers. This search has the greatest scope and may return a very large result set. If possible, search on at least one indexed attribute and set the referrals settings (see Performance and Handling Large Result Sets) to match your searching needs. It is also suggested that the results of a subtree search be performed asynchronously and paged to reduce the server overhead and network effectiveness. A subtree search is normally used to search objects for a given scope. For example, search for all users with accounts that will expire in 30 days or less.