1// $OpenLDAP$ 2/* 3 * Copyright 2000-2011 The OpenLDAP Foundation, All Rights Reserved. 4 * COPYING RESTRICTIONS APPLY, see COPYRIGHT file 5 */ 6 7#ifndef LDAP_CONNECTION_H 8#define LDAP_CONNECTION_H 9 10#include <LDAPSearchResults.h> 11#include <LDAPExtResult.h> 12#include <LDAPAsynConnection.h> 13 14/** Main class for synchronous LDAP-Communication 15 * 16 * The class represent a LDAP-Connection to perform synchronous 17 * LDAP-Operations. This provides methodes for the different 18 * LDAP-Operations. All the methods for the LDAP-operations block until 19 * all results for the operation are received or until an error occurs 20 */ 21class LDAPConnection : private LDAPAsynConnection { 22 23 public : 24 /** 25 * Constant for the Search-Operation to indicate a Base-Level 26 * Search 27 */ 28 static const int SEARCH_BASE; 29 30 /** 31 * Constant for the Search-Operation to indicate a One-Level 32 * Search 33 */ 34 static const int SEARCH_ONE; 35 36 /** 37 * Constant for the Search-Operation to indicate a Subtree 38 * Search 39 */ 40 static const int SEARCH_SUB; 41 42 /** This Constructor initializes synchronous LDAP-Connection 43 * 44 * During execution of this constructor no network communication 45 * is performed. Just some internal data structure are initialized 46 * @param hostname Name (or IP-Adress) of the destination host 47 * @param port Port the LDAP server is running on 48 * @param cons Default constraints to use with operations over 49 * this connection 50 */ 51 LDAPConnection(const std::string& hostname="localhost", int port=389, 52 LDAPConstraints* cons=new LDAPConstraints()); 53 54 /** 55 * Destructor 56 */ 57 ~LDAPConnection(); 58 59 /** 60 * Initzializes a synchronous connection to a server. 61 * 62 * There is actually no 63 * communication to the server. Just the object is initialized 64 * (e.g. this method is called within the 65 * LDAPConnection(char*,int,LDAPConstraints) constructor.) 66 * @param hostname The Name or IP-Address of the destination 67 * LDAP-Server 68 * @param port The Network Port the server is running on 69 */ 70 void init(const std::string& hostname, int port); 71 72 /** 73 * Start TLS on this connection. This isn't in the constructor, 74 * because it could fail (i.e. server doesn't have SSL cert, client 75 * api wasn't compiled against OpenSSL, etc.). 76 * @throws LDAPException if the TLS Layer could not be setup 77 * correctly 78 */ 79 void start_tls(); 80 81 /** 82 * Performs a simple authentication with the server 83 * 84 * @throws LDAPReferralException if a referral is received 85 * @throws LDAPException for any other error occuring during the 86 * operation 87 * @param dn The name of the entry to bind as 88 * @param passwd The cleartext password for the entry 89 */ 90 void bind(const std::string& dn="", const std::string& passwd="", 91 LDAPConstraints* cons=0); 92 void saslInteractiveBind(const std::string& mech, 93 int flags=0, 94 SaslInteractionHandler *sih=0, 95 const LDAPConstraints *cons=0); 96 97 /** 98 * Performs the UNBIND-operation on the destination server 99 * 100 * @throws LDAPException in any case of an error 101 */ 102 void unbind(); 103 104 /** 105 * Performs a COMPARE-operation on an entery of the destination 106 * server. 107 * 108 * @throws LDAPReferralException if a referral is received 109 * @throws LDAPException for any other error occuring during the 110 * operation 111 * @param dn Distinguished name of the entry for which the compare 112 * should be performed 113 * @param attr An Attribute (one (!) value) to use for the 114 * compare operation 115 * @param cons A set of constraints that should be used with this 116 * request 117 * @returns The result of the compare operation. true if the 118 * attr-parameter matched an Attribute of the entry. false if it 119 * did not match 120 */ 121 bool compare(const std::string& dn, const LDAPAttribute& attr, 122 LDAPConstraints* cons=0); 123 124 /** 125 * Deletes an entry from the directory 126 * 127 * This method performs the DELETE operation on the server 128 * @throws LDAPReferralException if a referral is received 129 * @throws LDAPException for any other error occuring during the 130 * operation 131 * @param dn Distinguished name of the entry that should be deleted 132 * @param cons A set of constraints that should be used with this 133 * request 134 */ 135 void del(const std::string& dn, const LDAPConstraints* cons=0); 136 137 /** 138 * Use this method to perform the ADD-operation 139 * 140 * @throws LDAPReferralException if a referral is received 141 * @throws LDAPException for any other error occuring during the 142 * operation 143 * @param le the entry to add to the directory 144 * @param cons A set of constraints that should be used with this 145 * request 146 */ 147 void add(const LDAPEntry* le, const LDAPConstraints* cons=0); 148 149 /** 150 * To modify the attributes of an entry, this method can be used 151 * 152 * @throws LDAPReferralException if a referral is received 153 * @throws LDAPException for any other error occuring during the 154 * operation 155 * @param dn The DN of the entry which should be modified 156 * @param mods A set of modifications for that entry. 157 * @param cons A set of constraints that should be used with this 158 * request 159 */ 160 void modify(const std::string& dn, const LDAPModList* mods, 161 const LDAPConstraints* cons=0); 162 163 /** 164 * This method performs the ModDN-operation. 165 * 166 * It can be used to rename or move an entry by modifing its DN. 167 * 168 * @throws LDAPReferralException if a referral is received 169 * @throws LDAPException for any other error occuring during the 170 * operation 171 * @param dn The DN that should be modified 172 * @param newRDN If the RDN of the entry should be modified the 173 * new RDN can be put here. 174 * @param delOldRDN If the old RDN should be removed from the 175 * entry's attribute this parameter has to be 176 * "true" 177 * @param newParentDN If the entry should be moved inside the 178 * DIT, the DN of the new parent of the entry 179 * can be given here. 180 * @param cons A set of constraints that should be used with this 181 * request 182 */ 183 void rename(const std::string& dn, const std::string& newRDN, 184 bool delOldRDN=false, const std::string& newParentDN="", 185 const LDAPConstraints* cons=0); 186 187 /** 188 * This method can be used for the sync. SEARCH-operation. 189 * 190 * @throws LDAPReferralException if a referral is received 191 * @throws LDAPException for any other error occuring during the 192 * operation 193 * @param base The distinguished name of the starting point for the 194 * search 195 * @param scope The scope of the search. Possible values: <BR> 196 * LDAPAsynConnection::SEARCH_BASE, <BR> 197 * LDAPAsynConnection::SEARCH_ONE, <BR> 198 * LDAPAsynConnection::SEARCH_SUB 199 * @param filter The std::string representation of a search filter to 200 * use with this operation 201 * @param attrsOnly true if only the attributes names (no values) 202 * should be returned 203 * @param cons A set of constraints that should be used with this 204 * request 205 * @returns A pointer to a LDAPSearchResults-object that can be 206 * used to read the results of the search. 207 */ 208 LDAPSearchResults* search(const std::string& base, int scope=0, 209 const std::string& filter="objectClass=*", 210 const StringList& attrs=StringList(), bool attrsOnly=false, 211 const LDAPConstraints* cons=0); 212 213 /** 214 * This method is for extended LDAP-Operations. 215 * 216 * @throws LDAPReferralException if a referral is received 217 * @throws LDAPException for any other error occuring during the 218 * operation 219 * @param oid The Object Identifier of the Extended Operation that 220 * should be performed. 221 * @param strint If the Extended Operation needs some additional 222 * data it can be passed to the server by this parameter. 223 * @param cons A set of constraints that should be used with this 224 * request 225 * @returns The result of the Extended Operation as an 226 * pointer to a LDAPExtResult-object. 227 */ 228 LDAPExtResult* extOperation(const std::string& oid, const std::string& 229 value="", const LDAPConstraints *const = 0); 230 231 const std::string& getHost() const; 232 233 int getPort() const; 234 235 void setConstraints(LDAPConstraints *cons); 236 237 const LDAPConstraints* getConstraints() const ; 238 TlsOptions getTlsOptions() const; 239}; 240 241#endif //LDAP_CONNECTION_H 242