The content on this page has been superseded by the release of Ruby/LDAP 0.8.4, which is the first release with me as the maintainer. All of the work discussed on this page is now available in version 0.8.4.
This is a series of patches to Ruby/LDAP 0.8.3 to allow the easy use of controls. Controls take advantage of the extensible nature of LDAPv3 to provide functionality not part of the original protocol specification.
Specifically, I had a need at work to use the Paged Results control, described in RFC2696. ruby-ldap 0.8.3 allows the client to set controls at the search level via LDAP::Conn#search_ext and LDAP::Conn#search_ext2, but it has no way to return controls sent by the server to the client as a side-effect of the search. Furthermore, I wanted to be able to set controls at the session level and have those be effective during LDAP::Conn#search and LDAP::Conn#search2, which are methods I use much more frequently.
| ruby-ldap-0.8.3-version.diff | This simply fixes the version number returned by ruby-ldap. It has not been incremented since 0.8.0 was released. You can skip this one if you want. | ruby-ldap-0.8.3-set-oid.diff | This is a one-line fix to ensure that the OID is properly set when creating a control. You should apply this. |
| ruby-ldap-0.8.3-controls.diff | This is the important one. This makes it possible to set controls at the session level. |
| ruby-ldap-0.8.3-controls-ruby.diff | This creates control.rb and extends the LDAP::Control class. This makes the ASN.1 and BER encoding of controls much more palatable to the end user. |
| ruby-ldap-0.8.3-bound.diff | This introduces LDAP::Conn#bound? for checking the status of an LDAP connection. The method returns true or false. It also raises an LDAP::ResultError exception if an attempt is made to set the LDAP protocol version after the bind has taken place. |
| ruby-ldap-0.8.3-sasl_quiet.diff | This adds a new accessor, LDAP::Conn#sasl_quiet for silencing SASL messages normally output by OpenLDAP. Set it to true to get it to do this. The default setting is false. Again, this patch isn't really needed. I made it to satisfy a requirement we had at work. |
If you apply the above patches, you will be able to use controls easily in your programs. The example program below demonstrates the use of the Paged Results control to return search results one page at a time.
Used against an Active Directory server, this will allow you to exceed the maximum number of search results that the server has been configured to return, by breaking the request into multiple pages. If you ask for a page size larger than the maximum number of results the server can return, the page size will be commuted to this maximum.
Unfortunately, OpenLDAP implements this control differently. It will return pages of results until the total number of results returned exceeds the server's limit. If you ask for a page size that is larger than this maximum number of search results allowed by the server, you will immediately receive an error. The page size will not be adjusted downwards for you.
Clearly, the Active Directory behaviour is actually more useful here, even though one of the OpenLDAP developers assures me that the OpenLDAP behaviour is the more correct, as far as the RFC is concerned.