void addServer ( nsILDAPServer server )

Add a (possibly) new LDAP server entry to the service. A server entry holds information about the host, port and other components of the LDAP URL, as well as information used for binding a connection to the LDAP server.

An LDAP Server entry (nsILDAPServer) contains the URL, user credentials, and other information related to the actual server itself. It is used for connecting, binding, rebinding, setting timeouts and so forth.

Arguments:

server: an nsILDAPServer object

AUTF8String createFilter ( PRUint32 maxSize , AUTF8String pattern , AUTF8String prefix , AUTF8String suffix , AUTF8String attr , AUTF8String value )

Generates and returns an LDAP search filter by substituting value, attr, prefix, and suffix into pattern.

The only good documentation I'm aware of for this function is at and Unfortunately, this does not currently seem to be available under any open source license, so I can't include that documentation here in the doxygen comments.

Arguments:

maxSize: maximum size (in char) of string to be created and returned (including final \0)

pattern: pattern to be used for the filter

prefix: prefix to prepend to the filter

suffix: suffix to be appended to the filer

attr: replacement for %a in the pattern

value: replacement for %v in the pattern

void deleteServer ( PRUnichar* key )

Mark an LDAP server, in the Service, as a candidate for deletion. If there are still leases ("users") of this server, the operation fails.

Arguments:

key: unique key identifying the server entry

nsILDAPConnection getConnection ( PRUnichar* key )

This is the nsLDAPConnection object related to this server. This does increase the lease counter on the object, so you have to call the releaseConnection() method to return it. It is important that you do this in matching pairs, and that you do not keep any dangling references to an object around after you have called the releaseConnection() method.

Arguments:

key: unique key identifying the server entry

nsILDAPServer getServer ( PRUnichar* key )

Get the nsILDAPServer object for the specified server entry in the service.

Arguments:

key: unique key identifying the server entry

void parseDn ( char* dn , out AUTF8String rdn , out AUTF8String baseDn , out PRUint32 rdnCount , out arrayof char* rdnAttrs )

Parses a distinguished name (DN) and returns the relative DN, base DN and the list of attributes that make up the relative DN.

Arguments:

dn: DN to parse

rdn: The relative DN for the given DN

baseDn: The base DN for the given DN

rdnCount: Number of values in the outbound attributes array.

rdnAttrs: Array of attribute names

void reconnectConnection ( PRUnichar* key , nsILDAPMessageListener listener )

If we detect that a connection is broken (server disconnected us, or any other problem with the link), we need to try to reestablish the connection. This is very similar to requestConnection(), except you use this when detecting an error with a connection that is being cached.

Arguments:

key: unique key identifying the server entry

listener

void releaseConnection ( PRUnichar* key )

Release the lease on a (cached) LDAP connection, making it a potential candidate for disconnection. Note that this will not delete the actual LDAP server entry in the service, it's still registered and can be used in future calls to requestConnection().

This API might be deprecated in the future, once we figure out how to use weak references to support our special needs for reference counting. For the time being, it is vital that you call this function when you're done with a Connection, and that you do not keep any copies of the Connection object lingering around.

Arguments:

key: unique key identifying the server entry

void requestConnection ( PRUnichar* key , nsILDAPMessageListener listener )

Request a connection from the service, asynchronously. If there is one "cached" already, we will actually call the callback function before returning from this function. This might be considered a bug, but for now be aware of this (see Bugzilla bug #75989).

Calling this method does not increment the leases on this connection, you'll have to use the getConnection() method to actually get the connection itself (presumably from the callback/listener object). The listener needs to implement nsILDAPMessageListener, providing the OnLDAPMessage() method.

Arguments:

key: unique key identifying the server entry

listener