1/*	$NetBSD: LDAPConnection.h,v 1.1.1.3 2010/12/12 15:18:45 adam Exp $	*/
2
3// OpenLDAP: pkg/ldap/contrib/ldapc++/src/LDAPConnection.h,v 1.8.4.3 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#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 methodes 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 */
23class 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-Adress) 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         * Initzializes 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 occuring 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 entery of the destination
108         * server.
109         *
110         * @throws LDAPReferralException if a referral is received
111         * @throws LDAPException for any other error occuring 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 occuring 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 occuring 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 occuring 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 modifing its DN.
169         *
170         * @throws LDAPReferralException if a referral is received
171         * @throws LDAPException for any other error occuring 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 occuring 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 occuring 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