/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- * * The contents of this file are subject to the Mozilla Public * License Version 1.1 (the "License"); you may not use this file * except in compliance with the License. You may obtain a copy of * the License at http://www.mozilla.org/MPL/ * * Software distributed under the License is distributed on an "AS * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or * implied. See the License for the specific language governing * rights and limitations under the License. * * The Original Code is the mozilla.org LDAP XPCOM component. * * The Initial Developer of the Original Code is Netscape * Communications Corporation. Portions created by Netscape are * Copyright (C) 2000 Netscape Communications Corporation. All * Rights Reserved. * * Contributor(s): Leif Hedstrom * Dan Mosedale * * Alternatively, the contents of this file may be used under the * terms of the GNU General Public License Version 2 or later (the * "GPL"), in which case the provisions of the GPL are applicable * instead of those above. If you wish to allow use of your * version of this file only under the terms of the GPL and not to * allow others to use your version of this file under the MPL, * indicate your decision by deleting the provisions above and * replace them with the notice and other provisions required by * the GPL. If you do not delete the provisions above, a recipient * may use your version of this file under either the MPL or the * GPL. */ #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(f73cc6c1-2301-484b-94a5-8885bca106d1)] 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 * and * * 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 PRUnichars) 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 */ AString createFilter(in unsigned long aMaxSize, in AString aPattern, in AString aPrefix, in AString aSuffix, in AString aAttr, in AString aValue); /** * Convert a Unicode string (AString) to a single byte string, using * UTF8 encoding. This is used to pass UTF8 encoded strings into the * nsILDAPURL interface for instance. Note that this method will go * away (hopefully) once we have a real solution (see bug 84186). * * @param aString Unicode string to be converted * @return UTF8 encoded string, single byte * * @exception NS_ERROR_NULL_POINTER NULL pointer * @exception NS_ERROR_OUT_OF_MEMORY ran out of memory */ string UCS2toUTF8(in AString aString); /** * Convert a UTF8 string (|string|) to a Unicode (|AString|) string. * Note that this method will go away (hopefully) once we have a * real solution (see bug 84186). * * @param string UTF8 string to be converted * @return Unicode string * * @exception NS_ERROR_OUT_OF_MEMORY ran out of memory */ AString UTF8toUCS2(in string aString); }; .