1 // $OpenLDAP: pkg/ldap/contrib/ldapc++/src/LDAPAsynConnection.h,v 1.11.2.4 2008/04/14 23:09:26 quanah Exp $ 2 /* 3 * Copyright 2000, OpenLDAP Foundation, All Rights Reserved. 4 * COPYING RESTRICTIONS APPLY, see COPYRIGHT file 5 */ 6 7 8 #ifndef LDAP_ASYN_CONNECTION_H 9 #define LDAP_ASYN_CONNECTION_H 10 11 #include<iostream> 12 #include<string> 13 14 #include<ldap.h> 15 #include<lber.h> 16 17 #include <LDAPEntry.h> 18 #include <LDAPException.h> 19 #include <LDAPMessageQueue.h> 20 #include <LDAPConstraints.h> 21 #include <LDAPModification.h> 22 #include <LDAPModList.h> 23 #include <LDAPUrl.h> 24 #include <LDAPUrlList.h> 25 #include <SaslInteractionHandler.h> 26 27 //* Main class for an asynchronous LDAP connection 28 /** 29 * This class represents an asynchronous connection to an LDAP-Server. It 30 * provides the methods for authentication, and all other LDAP-Operations 31 * (e.g. search, add, delete, etc.) 32 * All of the LDAP-Operations return a pointer to a LDAPMessageQueue-Object, 33 * which can be used to obtain the results of that operation. 34 * A basic example of this class could be like this: <BR> 35 * 1. Create a new LDAPAsynConnection Object: <BR> 36 * 2. Use the init-method to initialize the connection <BR> 37 * 3. Call the bind-method to authenticate to the directory <BR> 38 * 4. Obtain the bind results from the return LDAPMessageQueue-Object <BR> 39 * 5. Perform on of the operations on the directory (add, delete, search, ..) 40 * <BR> 41 * 6. Use the return LDAPMessageQueue to obtain the results of the operation 42 * <BR> 43 * 7. Close the connection (feature not implemented yet :) ) <BR> 44 */ 45 class LDAPAsynConnection{ 46 public : 47 /** 48 * Constant for the Search-Operation to indicate a Base-Level 49 * Search 50 */ 51 static const int SEARCH_BASE=0; 52 53 /** 54 * Constant for the Search-Operation to indicate a One-Level 55 * Search 56 */ 57 static const int SEARCH_ONE=1; 58 59 /** 60 * Constant for the Search-Operation to indicate a subtree 61 * Search 62 */ 63 static const int SEARCH_SUB=2; 64 65 /** Construtor that initializes a connection to a server 66 * @param hostname Name (or IP-Adress) of the destination host 67 * @param port Port the LDAP server is running on 68 * @param cons Default constraints to use with operations over 69 * this connection 70 */ 71 LDAPAsynConnection(const std::string& url=std::string("localhost"), 72 int port=0, LDAPConstraints *cons=new LDAPConstraints() ); 73 74 //* Destructor 75 virtual ~LDAPAsynConnection(); 76 77 /** 78 * Initializes a connection to a server. 79 * 80 * There actually no 81 * communication to the server. Just the object is initialized 82 * (e.g. this method is called within the 83 * LDAPAsynConnection(char*,int,LDAPConstraints) constructor.) 84 * @param hostname The Name or IP-Address of the destination 85 * LDAP-Server 86 * @param port The Network Port the server is running on 87 */ 88 void init(const std::string& hostname, int port); 89 90 /** 91 * Initializes a connection to a server. 92 * 93 * There actually no communication to the server. Just the 94 * object is initialized 95 * @param uri The LDAP-Uri for the destination 96 */ 97 void initialize(const std::string& uri); 98 99 /** 100 * Start TLS on this connection. This isn't in the constructor, 101 * because it could fail (i.e. server doesn't have SSL cert, client 102 * api wasn't compiled against OpenSSL, etc.). 103 * @throws LDAPException if the TLS Layer could not be setup 104 * correctly 105 */ 106 void start_tls(); 107 108 /** Simple authentication to a LDAP-Server 109 * 110 * @throws LDAPException If the Request could not be sent to the 111 * destination server, a LDAPException-object contains the 112 * error that occured. 113 * This method does a simple (username, password) bind to the server. 114 * Other, saver, authentcation methods are provided later 115 * @param dn the distiguished name to bind as 116 * @param passwd cleartext password to use 117 */ 118 LDAPMessageQueue* bind(const std::string& dn="", 119 const std::string& passwd="", 120 const LDAPConstraints *cons=0); 121 122 LDAPMessageQueue* saslBind(const std::string& mech, 123 const std::string& cred, 124 const LDAPConstraints *cons=0); 125 126 LDAPMessageQueue* saslInteractiveBind(const std::string& mech, 127 int flags=0, 128 SaslInteractionHandler *sih=0, 129 const LDAPConstraints *cons=0); 130 131 /** Performing a search on a directory tree. 132 * 133 * Use the search method to perform a search on the LDAP-Directory 134 * @throws LDAPException If the Request could not be sent to the 135 * destination server, a LDAPException-object contains the 136 * error that occured. 137 * @param base The distinguished name of the starting point for the 138 * search operation 139 * @param scope The scope of the search. Possible values: <BR> 140 * LDAPAsynConnection::SEARCH_BASE, <BR> 141 * LDAPAsynConnection::SEARCH_ONE, <BR> 142 * LDAPAsynConnection::SEARCH_SUB 143 * @param filter The std::string representation of a search filter to 144 * use with this operation 145 * @param attrsOnly true if only the attributes names (no values) 146 * should be returned 147 * @param cons A set of constraints that should be used with this 148 * request 149 */ 150 LDAPMessageQueue* search(const std::string& base="", int scope=0, 151 const std::string& filter="objectClass=*", 152 const StringList& attrs=StringList(), 153 bool attrsOnly=false, 154 const LDAPConstraints *cons=0); 155 156 /** Delete an entry from the directory 157 * 158 * This method sends a delete request to the server 159 * @throws LDAPException If the Request could not be sent to the 160 * destination server, a LDAPException-object contains the 161 * error that occured. 162 * @param dn Distinguished name of the entry that should be deleted 163 * @param cons A set of constraints that should be used with this 164 * request 165 */ 166 LDAPMessageQueue* del(const std::string& dn, const LDAPConstraints *cons=0); 167 168 /** 169 * Perform the COMPARE-operation on an attribute 170 * 171 * @throws LDAPException If the Request could not be sent to the 172 * destination server, a LDAPException-object contains the 173 * error that occured. 174 * @param dn Distinguished name of the entry for which the compare 175 * should be performed 176 * @param attr An Attribute (one (!) value) to use for the 177 * compare operation 178 * @param cons A set of constraints that should be used with this 179 * request 180 */ 181 LDAPMessageQueue* compare(const std::string& dn, 182 const LDAPAttribute& attr, 183 const LDAPConstraints *cons=0); 184 185 /** Add an entry to the directory 186 * 187 * @throws LDAPException If the Request could not be sent to the 188 * destination server, a LDAPException-object contains the 189 * error that occured. 190 * @param le The entry that will be added to the directory 191 */ 192 LDAPMessageQueue* add( const LDAPEntry* le, 193 const LDAPConstraints *const=0); 194 195 /** Apply modifications to attributes of an entry 196 * 197 * @throws LDAPException If the Request could not be sent to the 198 * destination server, a LDAPException-object contains the 199 * error that occured. 200 * @param dn Distiguished Name of the Entry to modify 201 * @param modlist A set of modification that should be applied 202 * to the Entry 203 * @param cons A set of constraints that should be used with this 204 * request 205 */ 206 LDAPMessageQueue* modify(const std::string& dn, 207 const LDAPModList *modlist, 208 const LDAPConstraints *cons=0); 209 210 /** modify the DN of an entry 211 * 212 * @throws LDAPException If the Request could not be sent to the 213 * destination server, a LDAPException-object contains the 214 * error that occured. 215 * @param dn DN to modify 216 * @param newRDN The new relative DN for the entry 217 * @param delOldRDN true=The old RDN will be removed from the 218 * attributes <BR> 219 * false=The old RDN will still be present in the 220 * attributes of the entry 221 * @param newParentDN The DN of the new parent entry of the entry 222 * 0 to keep the old one 223 */ 224 LDAPMessageQueue* rename(const std::string& dn, 225 const std::string& newRDN, 226 bool delOldRDN=false, const std::string& newParentDN="", 227 const LDAPConstraints* cons=0); 228 229 /** Perform a LDAP extended Operation 230 * 231 * @throws LDAPException If the Request could not be sent to the 232 * destination server, a LDAPException-object contains the 233 * error that occured. 234 * @param oid The dotted decimal representation of the extended 235 * Operation that should be performed 236 * @param value The data asociated with this operation 237 * @param cons A set of constraints that should be used with this 238 * request 239 */ 240 LDAPMessageQueue* extOperation(const std::string& oid, 241 const std::string& value="", const LDAPConstraints *cons=0); 242 243 /** End an outstanding request 244 * 245 * @param q All outstanding request related to this LDAPMessageQueue 246 * will be abandoned 247 */ 248 void abandon(LDAPMessageQueue *q); 249 250 /** 251 * Performs the UNBIND-operation on the destination server 252 * 253 * @throws LDAPException in any case of an error 254 */ 255 void unbind(); 256 257 /** 258 * @returns The C-APIs LDAP-structure that is associated with the 259 * current connection 260 */ 261 LDAP* getSessionHandle() const ; 262 263 /** 264 * @returns The Hostname of the destination server of the 265 * connection. 266 */ 267 const std::string& getHost() const; 268 269 /** 270 * @returns The Port to which this connection is connecting to on 271 * the remote server. 272 */ 273 int getPort() const; 274 275 /** Change the default constraints of the connection 276 * 277 * @parameter cons cons New LDAPConstraints to use with the connection 278 */ 279 void setConstraints(LDAPConstraints *cons); 280 281 /** Get the default constraints of the connection 282 * 283 * @return Pointer to the LDAPConstraints-Object that is currently 284 * used with the Connection 285 */ 286 const LDAPConstraints* getConstraints() const; 287 288 /** 289 * This method is used internally for automatic referral chasing. 290 * It tries to bind to a destination server of the URLs of a 291 * referral. 292 * 293 * @throws LDAPException in any case of an error 294 * @param urls Contains a std::list of LDAP-Urls that indicate the 295 * destinations of a referral 296 * @param usedUrl After this method has successfully bind to one of 297 * the Destination URLs this parameter contains the URLs 298 * which was contacted. 299 * @param cons An LDAPConstraints-Object that should be used for 300 * the new connection. If this object contains a 301 * LDAPRebind-object it is used to bind to the new server 302 */ 303 LDAPAsynConnection* referralConnect(const LDAPUrlList& urls, 304 LDAPUrlList::const_iterator& usedUrl, 305 const LDAPConstraints* cons) const; 306 307 private : 308 /** 309 * Private copy constructor. So nobody can call it. 310 */ 311 LDAPAsynConnection(const LDAPAsynConnection& lc){}; 312 313 /** 314 * A pointer to the C-API LDAP-structure that is associated with 315 * this connection 316 */ 317 LDAP *cur_session; 318 319 /** 320 * A pointer to the default LDAPConstrains-object that is used when 321 * no LDAPConstraints-parameter is provided with a call for a 322 * LDAP-operation 323 */ 324 LDAPConstraints *m_constr; 325 326 /** 327 * The URI of this connection 328 */ 329 LDAPUrl m_uri; 330 331 protected: 332 /** 333 * Is caching enabled? 334 */ 335 bool m_cacheEnabled; 336 }; 337 #endif //LDAP_ASYN_CONNECTION_H 338 339 340