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