ruby-ldap/ruby-net-ldap — pull request #26 by chessbyte (2011-12-28 20:33:35+00:00)
Title: Added Continuation Reference Processing as defined in section 4.5.3 of RFC 2251 (http://www.ietf.org/rfc/rfc2251.txt)

4.5.3. Continuation References in the Search Result

If the server was able to locate the entry referred to by the
baseObject but was unable to search all the entries in the scope at
and under the baseObject, the server may return one or more
SearchResultReference, each containing a reference to another set of
servers for continuing the operation. A server MUST NOT return any
SearchResultReference if it has not located the baseObject and
thus has not searched any entries; in this case it would return a
SearchResultDone containing a referral resultCode.

In the absence of indexing information provided to a server from
servers holding subordinate naming contexts, SearchResultReference
responses are not affected by search filters and are always returned
when in scope.

The SearchResultReference is of the same data type as the Referral.
URLs for servers implementing the LDAP protocol are written according
to [9]. The part MUST be present in the URL, with the new target
object name. The client MUST use this name in its next request.
Some servers (e.g. part of a distributed index exchange system) may
provide a different filter in the URLs of the SearchResultReference.
If the filter part of the URL is present in an LDAP URL, the client
MUST use the new filter in its next request to progress the search,
and if the filter part is absent the client will use again the same
filter. Other aspects of the new search request may be the same or
different as the search which generated the continuation references.

Other kinds of URLs may be returned so long as the operation could be
performed using that protocol.

The name of an unexplored subtree in a SearchResultReference need not
be subordinate to the base object.

In order to complete the search, the client MUST issue a new search
operation for each SearchResultReference that is returned. Note that
the abandon operation described in section 4.11 applies only to a
particular operation sent on a connection between a client and server,
and if the client has multiple outstanding search operations to
different servers, it MUST abandon each operation individually.

4.5.3.1. Example

For example, suppose the contacted server (hosta) holds the entry
"O=MNN,C=WW" and the entry "CN=Manager,O=MNN,C=WW". It knows that
either LDAP-capable servers (hostb) or (hostc) hold
"OU=People,O=MNN,C=WW" (one is the master and the other server a
shadow), and that LDAP-capable server (hostd) holds the subtree
"OU=Roles,O=MNN,C=WW". If a subtree search of "O=MNN,C=WW" is
requested to the contacted server, it may return the following:

SearchResultEntry for O=MNN,C=WW
SearchResultEntry for CN=Manager,O=MNN,C=WW
SearchResultReference {
ldap://hostb/OU=People,O=MNN,C=WW
ldap://hostc/OU=People,O=MNN,C=WW
}
SearchResultReference {
ldap://hostd/OU=Roles,O=MNN,C=WW
}
SearchResultDone (success)

Client implementors should note that when following a
SearchResultReference, additional SearchResultReference may be
generated. Continuing the example, if the client contacted the
server (hostb) and issued the search for the subtree
"OU=People,O=MNN,C=WW", the server might respond as follows:

SearchResultEntry for OU=People,O=MNN,C=WW
SearchResultReference {
ldap://hoste/OU=Managers,OU=People,O=MNN,C=WW
}
SearchResultReference {
ldap://hostf/OU=Consultants,OU=People,O=MNN,C=WW
}
SearchResultDone (success)

If the contacted server does not hold the base object for the search,
then it will return a referral to the client. For example, if the
client requests a subtree search of "O=XYZ,C=US" to hosta, the server
may return only a SearchResultDone containing a referral.

SearchResultDone (referral) {
ldap://hostg/
}