2 * Copyright 2000, OpenLDAP Foundation, All Rights Reserved.
3 * COPYING RESTRICTIONS APPLY, see COPYRIGHT file
7 #ifndef LDAP_ASYN_CONNECTION_H
8 #define LDAP_ASYN_CONNECTION_H
16 #include <LDAPMessageQueue.h>
17 #include <LDAPConstraints.h>
18 #include <LDAPModification.h>
19 #include <LDAPModList.h>
21 #include <LDAPUrlList.h>
26 //* Main class for an asynchronous LDAP connection
28 * This class represents an asynchronous connection to an LDAP-Server. It
29 * provides the methods for authentication, and all other LDAP-Operations
30 * (e.g. search, add, delete, etc.)
31 * All of the LDAP-Operations return a pointer to a LDAPMessageQueue-Object,
32 * which can be used to obtain the results of that operation.
33 * A basic example of this class could be like this: <BR>
34 * 1. Create a new LDAPAsynConnection Object: <BR>
35 * 2. Use the init-method to initialize the connection <BR>
36 * 3. Call the bind-method to authenticate to the directory <BR>
37 * 4. Obtain the bind results from the return LDAPMessageQueue-Object <BR>
38 * 5. Perform on of the operations on the directory (add, delete, search, ..)
40 * 6. Use the return LDAPMessageQueue to obtain the results of the operation
42 * 7. Close the connection (feature not implemented yet :) ) <BR>
44 class LDAPAsynConnection{
47 * Constant for the Search-Operation to indicate a Base-Level
50 static const int SEARCH_BASE=0;
53 * Constant for the Search-Operation to indicate a One-Level
56 static const int SEARCH_ONE=1;
59 * Constant for the Search-Operation to indicate a subtree
62 static const int SEARCH_SUB=2;
63 // static const int SEARCH_SUB=LDAP_SCOPE_SUBTREE;
64 // static const int SEARCH_ONE=LDAP_SCOPE_ONELEVEL;
65 // static const int SEARCH_SUB=LDAP_SCOPE_SUBTREE;
67 /** Construtor that initializes a connection to a server
68 * @param hostname Name (or IP-Adress) of the destination host
69 * @param port Port the LDAP server is running on
70 * @param cons Default constraints to use with operations over
73 LDAPAsynConnection(const std::string& hostname=std::string("localhost"),
74 int port=389, LDAPConstraints *cons=new LDAPConstraints() );
77 virtual ~LDAPAsynConnection();
80 * Initializes a connection to a server.
83 * communication to the server. Just the object is initialized
84 * (e.g. this method is called within the
85 * LDAPAsynConnection(char*,int,LDAPConstraints) constructor.)
86 * @param hostname The Name or IP-Address of the destination
88 * @param port The Network Port the server is running on
90 void init(const std::string& hostname, int port);
93 * Start TLS on this connection. This isn't in the constructor,
94 * because it could fail (i.e. server doesn't have SSL cert, client
95 * api wasn't compiled against OpenSSL, etc.). If you need TLS,
96 * then you should error if this call fails with an error code.
100 /** Simple authentication to a LDAP-Server
102 * @throws LDAPException If the Request could not be sent to the
103 * destination server, a LDAPException-object contains the
104 * error that occured.
105 * This method does a simple (username, password) bind to the server.
106 * Other, saver, authentcation methods are provided later
107 * @param dn the distiguished name to bind as
108 * @param passwd cleartext password to use
110 LDAPMessageQueue* bind(const std::string& dn="", const std::string& passwd="",
111 const LDAPConstraints *cons=0);
113 /** Performing a search on a directory tree.
115 * Use the search method to perform a search on the LDAP-Directory
116 * @throws LDAPException If the Request could not be sent to the
117 * destination server, a LDAPException-object contains the
118 * error that occured.
119 * @param base The distinguished name of the starting point for the
121 * @param scope The scope of the search. Possible values: <BR>
122 * LDAPAsynConnection::SEARCH_BASE, <BR>
123 * LDAPAsynConnection::SEARCH_ONE, <BR>
124 * LDAPAsynConnection::SEARCH_SUB
125 * @param filter The std::string representation of a search filter to
126 * use with this operation
127 * @param attrsOnly true if only the attributes names (no values)
129 * @param cons A set of constraints that should be used with this
132 LDAPMessageQueue* search(const std::string& base="", int scope=0,
133 const std::string& filter="objectClass=*",
134 const StringList& attrs=StringList(),
135 bool attrsOnly=false,
136 const LDAPConstraints *cons=0);
138 /** Delete an entry from the directory
140 * This method sends a delete request to the server
141 * @throws LDAPException If the Request could not be sent to the
142 * destination server, a LDAPException-object contains the
143 * error that occured.
144 * @param dn Distinguished name of the entry that should be deleted
145 * @param cons A set of constraints that should be used with this
148 LDAPMessageQueue* del(const std::string& dn, const LDAPConstraints *cons=0);
151 * Perform the COMPARE-operation on an attribute
153 * @throws LDAPException If the Request could not be sent to the
154 * destination server, a LDAPException-object contains the
155 * error that occured.
156 * @param dn Distinguished name of the entry for which the compare
157 * should be performed
158 * @param attr An Attribute (one (!) value) to use for the
160 * @param cons A set of constraints that should be used with this
163 LDAPMessageQueue* compare(const std::string& dn, const LDAPAttribute& attr,
164 const LDAPConstraints *cons=0);
166 /** Add an entry to the directory
168 * @throws LDAPException If the Request could not be sent to the
169 * destination server, a LDAPException-object contains the
170 * error that occured.
171 * @param le The entry that will be added to the directory
173 LDAPMessageQueue* add( const LDAPEntry* le,
174 const LDAPConstraints *const=0);
176 /** Apply modifications to attributes of an entry
178 * @throws LDAPException If the Request could not be sent to the
179 * destination server, a LDAPException-object contains the
180 * error that occured.
181 * @param dn Distiguished Name of the Entry to modify
182 * @param modstd::list A set of modification that should be applied
184 * @param cons A set of constraints that should be used with this
187 LDAPMessageQueue* modify(const std::string& dn, const LDAPModList *modlist,
188 const LDAPConstraints *cons=0);
190 /** modify the DN of an entry
192 * @throws LDAPException If the Request could not be sent to the
193 * destination server, a LDAPException-object contains the
194 * error that occured.
195 * @param dn DN to modify
196 * @param newRDN The new relative DN for the entry
197 * @param delOldRDN true=The old RDN will be removed from the
199 * false=The old RDN will still be present in the
200 * attributes of the entry
201 * @param newParentDN The DN of the new parent entry of the entry
202 * 0 to keep the old one
204 LDAPMessageQueue* rename(const std::string& dn, const std::string& newRDN,
205 bool delOldRDN=false, const std::string& newParentDN="",
206 const LDAPConstraints* cons=0);
208 /** Perform a LDAP extended Operation
210 * @throws LDAPException If the Request could not be sent to the
211 * destination server, a LDAPException-object contains the
212 * error that occured.
213 * @param oid The dotted decimal representation of the extended
214 * Operation that should be performed
215 * @param value The data asociated with this operation
216 * @param cons A set of constraints that should be used with this
219 LDAPMessageQueue* extOperation(const std::string& oid,
220 const std::string& value="", const LDAPConstraints *cons=0);
222 /** End an outstanding request
224 * @param q All outstanding request related to this LDAPMessageQueue
227 void abandon(LDAPMessageQueue *q);
230 * Performs the UNBIND-operation on the destination server
232 * @throws LDAPException in any case of an error
237 * @returns The C-APIs LDAP-structure that is associated with the
240 LDAP* getSessionHandle() const ;
243 * @returns The Hostname of the destination server of the
246 const std::string& getHost() const;
249 * @returns The Port to which this connection is connecting to on
254 /** Change the default constraints of the connection
256 * @parameter cons cons New LDAPConstraints to use with the connection
258 void setConstraints(LDAPConstraints *cons);
260 /** Get the default constraints of the connection
262 * @return Pointer to the LDAPConstraints-Object that is currently
263 * used with the Connection
265 const LDAPConstraints* getConstraints() const;
268 * This method is used internally for automatic referral chasing.
269 * It tries to bind to a destination server of the URLs of a
272 * @throws LDAPException in any case of an error
273 * @param urls Contains a std::list of LDAP-Urls that indicate the
274 * destinations of a referral
275 * @param usedUrl After this method has successfully bind to one of
276 * the Destination URLs this parameter contains the URLs
277 * which was contacted.
278 * @param cons An LDAPConstraints-Object that should be used for
279 * the new connection. If this object contains a
280 * LDAPRebind-object it is used to bind to the new server
282 LDAPAsynConnection* referralConnect(const LDAPUrlList& urls,
283 LDAPUrlList::const_iterator& usedUrl,
284 const LDAPConstraints* cons) const;
287 * Turn on caching, maxmem is in MB and timeout is in seconds.
288 * maxmem can be zero if you want to restrict caching by timeout only.
290 int enableCache(long timeout, long maxmem);
294 bool getCacheEnabled() { return m_cacheEnabled;};
295 /// uncache a specific dn. Used internally by methods that write.
296 void uncache_entry(std::string &dn);
297 /// used to clear the cache. Probably should be used after creating
298 /// an object that a cached search should find.
304 * Private copy constructor. So nobody can call it.
306 LDAPAsynConnection(const LDAPAsynConnection& lc){};
309 * A pointer to the C-API LDAP-structure that is associated with
315 * A pointer to the default LDAPConstrains-object that is used when
316 * no LDAPConstraints-parameter is provided with a call for a
319 LDAPConstraints *m_constr;
322 * The name of the destination host
327 * The port the destination server is running on.
333 * Is caching enabled?
337 #endif //LDAP_ASYN_CONNECTION_H