diff options
Diffstat (limited to 'ldap/xpcom/public/nsILDAPService.idl')
| -rw-r--r-- | ldap/xpcom/public/nsILDAPService.idl | 197 |
1 files changed, 197 insertions, 0 deletions
diff --git a/ldap/xpcom/public/nsILDAPService.idl b/ldap/xpcom/public/nsILDAPService.idl new file mode 100644 index 000000000..e4f8e75e6 --- /dev/null +++ b/ldap/xpcom/public/nsILDAPService.idl @@ -0,0 +1,197 @@ +/* -*- 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); +}; |