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