1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
2 *
3 * ***** BEGIN LICENSE BLOCK *****
4 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
5 *
6 * The contents of this file are subject to the Mozilla Public License Version
7 * 1.1 (the "License"); you may not use this file except in compliance with
8 * the License. You may obtain a copy of the License at
9 * http://www.mozilla.org/MPL/
10 *
11 * Software distributed under the License is distributed on an "AS IS" basis,
12 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
13 * for the specific language governing rights and limitations under the
14 * License.
15 *
16 * The Original Code is the mozilla.org LDAP XPCOM component.
17 *
18 * The Initial Developer of the Original Code is
19 * Netscape Communications Corporation.
20 * Portions created by the Initial Developer are Copyright (C) 2000
21 * the Initial Developer. All Rights Reserved.
22 *
23 * Contributor(s):
24 * Leif Hedstrom <leif@netscape.com>
25 * Dan Mosedale <dmose@netscape.com>
26 * Jeremy Laine <jeremy.laine@m4x.org>
27 *
28 * Alternatively, the contents of this file may be used under the terms of
29 * either the GNU General Public License Version 2 or later (the "GPL"), or
30 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
31 * in which case the provisions of the GPL or the LGPL are applicable instead
32 * of those above. If you wish to allow use of your version of this file only
33 * under the terms of either the GPL or the LGPL, and not to allow others to
34 * use your version of this file under the terms of the MPL, indicate your
35 * decision by deleting the provisions above and replace them with the notice
36 * and other provisions required by the GPL or the LGPL. If you do not delete
37 * the provisions above, a recipient may use your version of this file under
38 * the terms of any one of the MPL, the GPL or the LGPL.
39 *
40 * ***** END LICENSE BLOCK ***** */
41
42 #include "nsISupports.idl"
43 interface nsILDAPServer;
44 interface nsILDAPConnection;
45 interface nsILDAPMessageListener;
46
47 /**
48 * This interface provides an LDAP connection management service.
49 * It's used to cache already established LDAP connections, as well
50 * as reaping unused connections after a certain time period. This
51 * is done completely asynchronously, using callback functions.
52 */
53
54
55 [scriptable, uuid(69de6fbc-2e8c-4482-bf14-358d68b785d1)]
56 interface nsILDAPService : nsISupports {
57
58 /**
59 * Add a (possibly) new LDAP server entry to the service. A
60 * server entry holds information about the host, port and
61 * other components of the LDAP URL, as well as information
62 * used for binding a connection to the LDAP server.
63 *
64 * An LDAP Server entry (nsILDAPServer) contains the URL,
65 * user credentials, and other information related to the actual
66 * server itself. It is used for connecting, binding, rebinding,
67 * setting timeouts and so forth.
68 *
69 * @param aServer an nsILDAPServer object
70 *
71 * @exception NS_ERROR_FAILURE the server has already been
72 * added to the service
73 * @exception NS_ERROR_NULL_POINTER NULL pointer
74 * @exception NS_ERROR_OUT_OF_MEMORY ran out of memory
75 */
76 void addServer(in nsILDAPServer aServer);
77
78 /**
79 * Mark an LDAP server, in the Service, as a candidate for
80 * deletion. If there are still leases ("users") of this server,
81 * the operation fails.
82 *
83 * @param aKey unique key identifying the server entry
84 *
85 * @exception NS_ERROR_FAILURE either the server doesn't
86 * exist, or there are still
87 * leases oustanding
88 */
89 void deleteServer(in wstring aKey);
90
91 /**
92 * Get the nsILDAPServer object for the specified server entry
93 * in the service.
94 *
95 * @param aKey unique key identifying the server entry
96 *
97 * @exception NS_ERROR_FAILURE there is no server registered
98 * in the service with this key
99 * @exception NS_ERROR_NULL_POINTER NULL pointer
100 */
101 nsILDAPServer getServer(in wstring aKey);
102
103 /**
104 * Request a connection from the service, asynchronously. If there is
105 * one "cached" already, we will actually call the callback function
106 * before returning from this function. This might be considered a bug,
107 * but for now be aware of this (see Bugzilla bug #75989).
108 *
109 * Calling this method does not increment the leases on this connection,
110 * you'll have to use the getConnection() method to actually get the
111 * connection itself (presumably from the callback/listener object).
112 * The listener needs to implement nsILDAPMessageListener, providing
113 * the OnLDAPMessage() method.
114 *
115 * @param aKey unique key identifying the server entry
116 * @param aMessageListener the listener object, which we will call
117 * when the LDAP bind message is available
118 *
119 * @exception NS_ERROR_FAILURE there is no server registered
120 * in the service with this key,
121 * or we were unable to get a
122 * connection properly to the server
123 * @exception NS_ERROR_NOT_AVAILABLE couldn't create connection thread
124 * @exception NS_ERROR_OUT_OF_MEMORY ran out of memory
125 * @exception NS_ERROR_UNEXPECTED unknown or unexpected error...
126 */
127 void requestConnection(in wstring aKey,
128 in nsILDAPMessageListener aListener);
129
130 /**
131 * This is the nsLDAPConnection object related to this server.
132 * This does increase the lease counter on the object, so you have
133 * to call the releaseConnection() method to return it. It is
134 * important that you do this in matching pairs, and that you do
135 * not keep any dangling references to an object around after you
136 * have called the releaseConnection() method.
137 *
138 * @param aKey unique key identifying the server entry
139 *
140 * @exception NS_ERROR_FAILURE there is no server registered
141 * in the service with this key
142 * @exception NS_ERROR_NULL_POINTER NULL pointer
143 */
144 nsILDAPConnection getConnection(in wstring aKey);
145
146 /**
147 * Release the lease on a (cached) LDAP connection, making it a
148 * potential candidate for disconnection. Note that this will not
149 * delete the actual LDAP server entry in the service, it's still
150 * registered and can be used in future calls to requestConnection().
151 *
152 * This API might be deprecated in the future, once we figure out how
153 * to use weak references to support our special needs for reference
154 * counting. For the time being, it is vital that you call this function
155 * when you're done with a Connection, and that you do not keep any
156 * copies of the Connection object lingering around.
157 *
158 * @param aKey unique key identifying the server entry
159 *
160 * @exception NS_ERROR_FAILURE there is no server registered
161 * in the service with this key
162 * @exception NS_ERROR_OUT_OF_MEMORY ran out of memory
163 */
164 void releaseConnection(in wstring aKey);
165
166 /**
167 * If we detect that a connection is broken (server disconnected us,
168 * or any other problem with the link), we need to try to reestablish
169 * the connection. This is very similar to requestConnection(),
170 * except you use this when detecting an error with a connection
171 * that is being cached.
172 *
173 * @param aKey unique key identifying the server entry
174 * @param aMessageListener the listener object, which we will call
175 * when the LDAP bind message is available
176 *
177 * @exception NS_ERROR_FAILURE there is no server registered
178 * in the service with this key,
179 * or we were unable to get a
180 * connection properly to the server
181 * @exception NS_ERROR_NOT_AVAILABLE couldn't create connection thread
182 * @exception NS_ERROR_OUT_OF_MEMORY ran out of memory
183 * @exception NS_ERROR_UNEXPECTED unknown or unexpected error...
184 */
185 void reconnectConnection(in wstring aKey,
186 in nsILDAPMessageListener aListener);
187
188 /**
189 * Generates and returns an LDAP search filter by substituting
190 * aValue, aAttr, aPrefix, and aSuffix into aPattern.
191 *
192 * The only good documentation I'm aware of for this function is
193 * at <http://docs.iplanet.com/docs/manuals/dirsdk/csdk41/html/filter.htm>
194 * and
195 * <http://docs.iplanet.com/docs/manuals/dirsdk/csdk41/html/function.htm#17835>
196 * Unfortunately, this does not currently seem to be available
197 * under any open source license, so I can't include that
198 * documentation here in the doxygen comments.
199 *
200 * @param aMaxSize maximum size (in char) of string to be
201 * created and returned (including final \0)
202 * @param aPattern pattern to be used for the filter
203 * @param aPrefix prefix to prepend to the filter
204 * @param aSuffix suffix to be appended to the filer
205 * @param aAttr replacement for %a in the pattern
206 * @param aValue replacement for %v in the pattern
207 *
208 * @exception NS_ERROR_INVALID_ARG invalid parameter passed in
209 * @exception NS_ERROR_OUT_OF_MEMORY allocation failed
210 * @exception NS_ERROR_NOT_AVAILABLE filter longer than maxsiz chars
211 * @exception NS_ERROR_UNEXPECTED ldap_create_filter returned
212 * unexpected error code
213 */
214 AUTF8String createFilter(in unsigned long aMaxSize, in AUTF8String aPattern,
215 in AUTF8String aPrefix, in AUTF8String aSuffix,
216 in AUTF8String aAttr, in AUTF8String aValue);
217
218 /**
219 * Parses a distinguished name (DN) and returns the relative DN,
220 * base DN and the list of attributes that make up the relative DN.
221 *
222 * @param dn DN to parse
223 * @param rdn The relative DN for the given DN
224 * @param baseDn The base DN for the given DN
225 * @param rdnCount Number of values in the outbound attributes array.
226 * @param rdnAttrs Array of attribute names
227 *
228 */
229 void parseDn(in string dn, out AUTF8String rdn, out AUTF8String baseDn,
230 out unsigned long rdnCount,
231 [retval, array, size_is(rdnCount)] out string rdnAttrs);
232 };