summaryrefslogtreecommitdiffstats
path: root/ldap/xpcom/public/nsILDAPService.idl
diff options
context:
space:
mode:
Diffstat (limited to 'ldap/xpcom/public/nsILDAPService.idl')
-rw-r--r--ldap/xpcom/public/nsILDAPService.idl197
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);
+};