Back to index

lightning-sunbird  0.9+nobinonly
Public Member Functions
nsILDAPService Interface Reference

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

import "nsILDAPService.idl";

Inheritance diagram for nsILDAPService:
Inheritance graph
[legend]
Collaboration diagram for nsILDAPService:
Collaboration graph
[legend]

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.

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.

Definition at line 55 of file nsILDAPService.idl.


Member Function Documentation

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:
aServeran nsILDAPServer object
Exceptions:
NS_ERROR_FAILUREthe server has already been added to the service
NS_ERROR_NULL_POINTERNULL pointer
NS_ERROR_OUT_OF_MEMORYran 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:
aMaxSizemaximum size (in char) of string to be created and returned (including final \0)
aPatternpattern to be used for the filter
aPrefixprefix to prepend to the filter
aSuffixsuffix to be appended to the filer
aAttrreplacement for a in the pattern
aValuereplacement for v in the pattern
Exceptions:
NS_ERROR_INVALID_ARGinvalid parameter passed in
NS_ERROR_OUT_OF_MEMORYallocation failed
NS_ERROR_NOT_AVAILABLEfilter longer than maxsiz chars
NS_ERROR_UNEXPECTEDldap_create_filter returned unexpected error code

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:
aKeyunique key identifying the server entry
Exceptions:
NS_ERROR_FAILUREeither the server doesn't exist, or there are still leases oustanding

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:
aKeyunique key identifying the server entry
Exceptions:
NS_ERROR_FAILUREthere is no server registered in the service with this key
NS_ERROR_NULL_POINTERNULL pointer

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

Parameters:
aKeyunique key identifying the server entry
Exceptions:
NS_ERROR_FAILUREthere is no server registered in the service with this key
NS_ERROR_NULL_POINTERNULL pointer

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:
aKeyunique key identifying the server entry
aMessageListenerthe listener object, which we will call when the LDAP bind message is available
Exceptions:
NS_ERROR_FAILUREthere 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_AVAILABLEcouldn't create connection thread
NS_ERROR_OUT_OF_MEMORYran out of memory
NS_ERROR_UNEXPECTEDunknown or unexpected error...

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:
aKeyunique key identifying the server entry
Exceptions:
NS_ERROR_FAILUREthere is no server registered in the service with this key
NS_ERROR_OUT_OF_MEMORYran out of memory

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:
aKeyunique key identifying the server entry
aMessageListenerthe listener object, which we will call when the LDAP bind message is available
Exceptions:
NS_ERROR_FAILUREthere 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_AVAILABLEcouldn't create connection thread
NS_ERROR_OUT_OF_MEMORYran out of memory
NS_ERROR_UNEXPECTEDunknown or unexpected error...

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