/usr/share/idl/thunderbird/nsILDAPService.idl is in thunderbird-dev 1:52.7.0+build1-0ubuntu1.
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 | /* -*- 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);
};
|