/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
*
* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#include "nsISupports.idl"
interface nsILDAPServer;
interface nsILDAPConnection;
interface nsILDAPMessageListener;
/**
* 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.
*/
[scriptable, uuid(69de6fbc-2e8c-4482-bf14-358d68b785d1)]
interface nsILDAPService : nsISupports {
/**
* 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.
*
* @param aServer an nsILDAPServer object
*
* @exception NS_ERROR_FAILURE the server has already been
* added to the service
* @exception NS_ERROR_NULL_POINTER NULL pointer
* @exception NS_ERROR_OUT_OF_MEMORY ran out of memory
*/
void addServer(in nsILDAPServer aServer);
/**
* Mark an LDAP server, in the Service, as a candidate for
* deletion. If there are still leases ("users") of this server,
* the operation fails.
*
* @param aKey unique key identifying the server entry
*
* @exception NS_ERROR_FAILURE either the server doesn't
* exist, or there are still
* leases oustanding
*/
void deleteServer(in wstring aKey);
/**
* Get the nsILDAPServer object for the specified server entry
* in the service.
*
* @param aKey unique key identifying the server entry
*
* @exception NS_ERROR_FAILURE there is no server registered
* in the service with this key
* @exception NS_ERROR_NULL_POINTER NULL pointer
*/
nsILDAPServer getServer(in wstring aKey);
/**
* 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.
*
* @param aKey unique key identifying the server entry
* @param aMessageListener the listener object, which we will call
* when the LDAP bind message is available
*
* @exception 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
* @exception NS_ERROR_NOT_AVAILABLE couldn't create connection thread
* @exception NS_ERROR_OUT_OF_MEMORY ran out of memory
* @exception NS_ERROR_UNEXPECTED unknown or unexpected error...
*/
void requestConnection(in wstring aKey,
in nsILDAPMessageListener aListener);
/**
* 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.
*
* @param aKey unique key identifying the server entry
*
* @exception NS_ERROR_FAILURE there is no server registered
* in the service with this key
* @exception NS_ERROR_NULL_POINTER NULL pointer
*/
nsILDAPConnection getConnection(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.
*
* @param aKey unique key identifying the server entry
*
* @exception NS_ERROR_FAILURE there is no server registered
* in the service with this key
* @exception NS_ERROR_OUT_OF_MEMORY ran out of memory
*/
void releaseConnection(in wstring aKey);
/**
* 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.
*
* @param aKey unique key identifying the server entry
* @param aMessageListener the listener object, which we will call
* when the LDAP bind message is available
*
* @exception 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
* @exception NS_ERROR_NOT_AVAILABLE couldn't create connection thread
* @exception NS_ERROR_OUT_OF_MEMORY ran out of memory
* @exception NS_ERROR_UNEXPECTED unknown or unexpected error...
*/
void reconnectConnection(in wstring aKey,
in nsILDAPMessageListener aListener);
/**
* 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.
*
* @param aMaxSize maximum size (in char) of string to be
* created and returned (including final \0)
* @param aPattern pattern to be used for the filter
* @param aPrefix prefix to prepend to the filter
* @param aSuffix suffix to be appended to the filer
* @param aAttr replacement for %a in the pattern
* @param aValue replacement for %v in the pattern
*
* @exception NS_ERROR_INVALID_ARG invalid parameter passed in
* @exception NS_ERROR_OUT_OF_MEMORY allocation failed
* @exception NS_ERROR_NOT_AVAILABLE filter longer than maxsiz chars
* @exception NS_ERROR_UNEXPECTED ldap_create_filter returned
* unexpected error code
*/
AUTF8String createFilter(in unsigned long aMaxSize, in AUTF8String aPattern,
in AUTF8String aPrefix, in AUTF8String aSuffix,
in AUTF8String aAttr, in AUTF8String aValue);
/**
* Parses a distinguished name (DN) and returns the relative DN,
* base DN and the list of attributes that make up the relative DN.
*
* @param dn DN to parse
* @param rdn The relative DN for the given DN
* @param baseDn The base DN for the given DN
* @param rdnCount Number of values in the outbound attributes array.
* @param rdnAttrs Array of attribute names
*
*/
void parseDn(in string dn, out AUTF8String rdn, out AUTF8String baseDn,
out unsigned long rdnCount,
[retval, array, size_is(rdnCount)] out string rdnAttrs);
};