This section contains general information that is helpful to understand before you begin developing with the LDAP Classes for C#. This section contains information on LDAP connections, asynchronous and synchronous methods, constraints, LDAP messages, and LDAP URLs. The namespace used in the C# LDAP SDK is Novell.Directory.Ldap.
The central LDAP class is an LdapConnection. This class provides methods to establish an authenticated or anonymous connection to an LDAP server, as well as methods to search for, modify, compare, and delete entries in the directory.
The following code demonstrates the use of an LdapConnection object to connect to an LDAP server:
String ldapHost = "localhost"; int ldapPort = 389; LdapConnection ldapConn = new LdapConnection(); ldapConn.Connect( ldapHost, ldapPort );
These four lines use the LdapConnection object to create an anonymous connection to the LDAP server specified by ldapHost, and the port specified by ldapPort. At this point, you may authenticate to the server using the bind method, or perform another operation.
The LdapConnection class also provides methods for managing settings that are specific to the LDAP session (such as limits on the number of results returned or time-out limits). An LdapConnection object can be cloned, allowing objects to share a single network connection in a thread-safe manner.
Blocking versus Non-Blocking: The LDAP protocol provides both synchronous and asynchronous functions. For the synchronous search methods you can set the batch size parameter for functionality similar to the asynchronous search methods.
Asynchronous functions do not block, they return immediately after initiating the operation. One of the Listener class functions is used to retrieve the results.
Synchronous functions with batch size of zero block until all the results have been received from the server. Synchronous search functions with batch size = n: (non-zero) Block until "n" messages have been received from the server, then let enumeration proceed while queuing additional messages.
The default value of the batch size parameter is 1. Thus by default, an enumeration of search results from a synchronous search operation will return messages as they are received from the server. The enumeration will block if no messages are waiting.
Other differences between asynchronous and synchronous operations are detailed in the operation-specific sections, such as exception handling and referral handling.
Before you can make a non-encrypted connection, the LDAP server must be configured to allow the clear-text passwords.
LDAP constraints are used to control LDAP operations, allowing you to control the way in which operations are performed. Using constraints you can, for example, enable referral handling, set referral hop limits, and set controls to be sent to the server.
LDAP URLs provide a uniform method to access information on an LDAP server. Defined in RFC 2255, LDAP URLs begin with the prefix LDAP:// or LDAPS://. The following provides the syntax and descriptions of an LDAP URL.
ldap[s]://<hostname>:<port>/<base_dn>?<attributes>?<scope>?<filter>?<extension>
Note that ldaps is a common enhancement used to denote SSL, and is not defined in an RFC.
Table 2-1 Field Descriptions of an LDAP URL
NOTE:An attribute list is required if you want to provide a scope (even if the attribute list is blank). To return all attributes within a specific scope you must include <base_dn>??<scope>.
The SDK provides an LdapUrl class to handle LDAP URLs. This class has methods to store, parse, and manage LDAP URLs.
If you receive an LdapReferralExeption, you can retrieve a list of referral URLs using the LdapReferralException.getReferrals method. This method returns an array of LDAP URL Strings, which can be converted to LDAPUrls and passed directly to LDAP searches, or can be examined to determine whether or not you wish to follow the referrals.
The LdapMessage class represents the base class for LDAP response messages for asynchronous commands.
For all asynchronous operations you are returned a listener object. Methods of this listener object return an LdapResponse (a subclass of LdapMessage), which contains the result of the operation.
When performing an asynchronous search, a number of LdapMessage objects are returned. These messages can be one of three sub-types:
In your code, you need to determine the message type and handle it appropriately.
For example, you could perform an asynchronous search and receive nine LDAP messages. Seven of these could be LdapSearchResults, one could be an LdapSearchResultReference, and the last one is an LdapResponse. In your code, you set up conditional statements to determine the message type and handle it appropriately.