Public Member Functions

nsILDAPService Interface Reference

This interface provides an LDAP connection management service. More...

import "nsILDAPService.idl";

List of all members.

Public Member Functions

void addServer (in nsILDAPServer aServer)
 Add a (possibly) new LDAP server entry to the service.
void deleteServer (in wstring aKey)
 Mark an LDAP server, in the Service, as a candidate for deletion.
nsILDAPServer getServer (in wstring aKey)
 Get the nsILDAPServer object for the specified server entry in the service.
void requestConnection (in wstring aKey, in nsILDAPMessageListener aListener)
 Request a connection from the service, asynchronously.
nsILDAPConnection getConnection (in wstring aKey)
 This is the nsLDAPConnection object related to this server.
void releaseConnection (in wstring aKey)
 Release the lease on a (cached) LDAP connection, making it a potential candidate for disconnection.
void reconnectConnection (in wstring aKey, in nsILDAPMessageListener aListener)
 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.
AUTF8String createFilter (in unsigned long aMaxSize, in AUTF8String aPattern, in AUTF8String aPrefix, in AUTF8String aSuffix, in AUTF8String aAttr, in AUTF8String aValue)
 Generates and returns an LDAP search filter by substituting aValue, aAttr, aPrefix, and aSuffix into aPattern.
void parseDn (in string dn, out AUTF8String rdn, out AUTF8String baseDn, out unsigned long rdnCount,[retval, array, size_is(rdnCount)] out string rdnAttrs)
 Parses a distinguished name (DN) and returns the relative DN, base DN and the list of attributes that make up the relative DN.

Detailed Description

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.


Member Function Documentation

void nsILDAPService::addServer ( in nsILDAPServer  aServer  ) 

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.

Parameters:
aServer an nsILDAPServer object
Exceptions:
NS_ERROR_FAILURE the server has already been added to the service
NS_ERROR_NULL_POINTER NULL pointer
NS_ERROR_OUT_OF_MEMORY ran out of memory
AUTF8String nsILDAPService::createFilter ( in unsigned long  aMaxSize,
in AUTF8String  aPattern,
in AUTF8String  aPrefix,
in AUTF8String  aSuffix,
in AUTF8String  aAttr,
in AUTF8String  aValue 
)

Generates and returns an LDAP search filter by substituting aValue, aAttr, aPrefix, and aSuffix into aPattern.

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.

Parameters:
aMaxSize maximum size (in char) of string to be created and returned (including final )
aPattern pattern to be used for the filter
aPrefix prefix to prepend to the filter
aSuffix suffix to be appended to the filer
aAttr replacement for a in the pattern
aValue replacement for v in the pattern
Exceptions:
NS_ERROR_INVALID_ARG invalid parameter passed in
NS_ERROR_OUT_OF_MEMORY allocation failed
NS_ERROR_NOT_AVAILABLE filter longer than maxsiz chars
NS_ERROR_UNEXPECTED ldap_create_filter returned unexpected error code
void nsILDAPService::deleteServer ( in wstring  aKey  ) 

Mark an LDAP server, in the Service, as a candidate for deletion.

If there are still leases ("users") of this server, the operation fails.

Parameters:
aKey unique key identifying the server entry
Exceptions:
NS_ERROR_FAILURE either the server doesn't exist, or there are still leases oustanding
nsILDAPConnection nsILDAPService::getConnection ( in wstring  aKey  ) 

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.

Parameters:
aKey unique key identifying the server entry
Exceptions:
NS_ERROR_FAILURE there is no server registered in the service with this key
NS_ERROR_NULL_POINTER NULL pointer
nsILDAPServer nsILDAPService::getServer ( in wstring  aKey  ) 

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

Parameters:
aKey unique key identifying the server entry
Exceptions:
NS_ERROR_FAILURE there is no server registered in the service with this key
NS_ERROR_NULL_POINTER NULL pointer
void nsILDAPService::parseDn ( in string  dn,
out AUTF8String  rdn,
out AUTF8String  baseDn,
out unsigned long  rdnCount,
[retval, array, size_is(rdnCount)] out string  rdnAttrs 
)

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

Parameters:
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 nsILDAPService::reconnectConnection ( in wstring  aKey,
in nsILDAPMessageListener  aListener 
)

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.

Parameters:
aKey unique key identifying the server entry
aMessageListener the listener object, which we will call when the LDAP bind message is available
Exceptions:
NS_ERROR_FAILURE there is no server registered in the service with this key, or we were unable to get a connection properly to the server
NS_ERROR_NOT_AVAILABLE couldn't create connection thread
NS_ERROR_OUT_OF_MEMORY ran out of memory
NS_ERROR_UNEXPECTED unknown or unexpected error...
void nsILDAPService::releaseConnection ( in wstring  aKey  ) 

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.

Parameters:
aKey unique key identifying the server entry
Exceptions:
NS_ERROR_FAILURE there is no server registered in the service with this key
NS_ERROR_OUT_OF_MEMORY ran out of memory
void nsILDAPService::requestConnection ( in wstring  aKey,
in nsILDAPMessageListener  aListener 
)

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.

Parameters:
aKey unique key identifying the server entry
aMessageListener the listener object, which we will call when the LDAP bind message is available
Exceptions:
NS_ERROR_FAILURE there is no server registered in the service with this key, or we were unable to get a connection properly to the server
NS_ERROR_NOT_AVAILABLE couldn't create connection thread
NS_ERROR_OUT_OF_MEMORY ran out of memory
NS_ERROR_UNEXPECTED unknown or unexpected error...

The documentation for this interface was generated from the following file: