/usr/share/idl/thunderbird-11.0.1/nsILDAPService.idl is in thunderbird-dev 11.0.1+build1-0ubuntu2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 | /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
*
* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* 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 the Initial Developer are Copyright (C) 2000
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
* Leif Hedstrom <leif@netscape.com>
* Dan Mosedale <dmose@netscape.com>
* Jeremy Laine <jeremy.laine@m4x.org>
*
* Alternatively, the contents of this file may be used under the terms of
* either the GNU General Public License Version 2 or later (the "GPL"), or
* the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#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);
};
|