nsILDAPService

IID:f73cc6c1-2301-484b-94a5-8885bca106d1
Inherits From:nsISupports

This interface provides an LDAP connection management service. It's used to cache already established LDAP connections, as well as reaping unused connections after a certain time period. This is done completely asynchronously, using callback functions.

This interface is intended to be used as a service.

This interface is implemented by the following components:


Methods

void addServer ( nsILDAPServer server ) AUTF8String createFilter ( PRUint32 maxSize , AUTF8String pattern , AUTF8String prefix , AUTF8String suffix , AUTF8String attr , AUTF8String value ) void deleteServer ( PRUnichar* key ) nsILDAPConnection getConnection ( PRUnichar* key ) nsILDAPServer getServer ( PRUnichar* key ) void reconnectConnection ( PRUnichar* key , nsILDAPMessageListener listener ) void releaseConnection ( PRUnichar* key ) void requestConnection ( PRUnichar* key , nsILDAPMessageListener listener )

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 <http://docs.iplanet.com/docs/manuals/dirsdk/csdk41/html/filter.htm> and <">http://docs.iplanet.com/docs/manuals/dirsdk/csdk41/html/function.htm#17835> 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 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

Reference documentation is generated from Mozilla's source.

Add a note User Contributed Notes
No comments available

Copyright © 1999 - 2005 XULPlanet.com