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