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